Skip to main content

Installation & Setup

This guide walks you through installing the GrantFlow CLI and configuring it for your environment. You'll be up and running in just a few minutes.

System Requirements​

The GrantFlow CLI runs on macOS, Linux, and Windows. You'll need an active Azure Entra ID account with access to your organization's GrantFlow tenant.

Installation​

Choose the installation method that best fits your operating system and workflow.

note

Direct downloads will be available soon from our download portal. Until then, use Homebrew (macOS or existing Linuxbrew) or Windows Package Manager (winget). If you require a direct download temporarily, contact info@grantflow.cloud.

macOS​

You can install the CLI using Homebrew for easy updates and management:

macOS Installation
brew tap grantflow/cli
brew install grantflow

Direct downloads for macOS will be available from our download portal. If you need a package before that portal is live, please email info@grantflow.cloud.

Linux​

If you already use Homebrew on Linux (Linuxbrew), you can install using:

Linux Installation (Homebrew)
brew install grantflow

Otherwise, direct downloads for Linux will be available from our download portal. If you need a package before that portal is live, please email info@grantflow.cloud.

Windows​

Install using Windows Package Manager:

Windows Installation
winget install GrantFlow.CLI

Direct downloads for Windows will be available from our download portal. If you need a package before that portal is live, please email info@grantflow.cloud.

Verify Installation​

Confirm the CLI is installed correctly by checking the version:

Verify Installation
grantflow --version

You should see output similar to:

grantflow version 0.1.0

Initial Configuration​

The CLI requires a few pieces of information to connect to your GrantFlow tenant. You can configure these values using a configuration file, environment variables, or command-line flags.

Configuration File​

Create a configuration file at ~/.grantflow/config.yaml:

~/.grantflow/config.yaml
api_url: "https://api.grantflow.cloud"
tenant_id: "your-azure-tenant-id"
client_id: "your-grantflow-client-id"
output: "table"

Replace your-azure-tenant-id and your-grantflow-client-id with the values provided by your GrantFlow administrator.

tip

Your administrator can find these values in the GrantFlow admin portal under Settings → API Configuration.

Environment Variables​

Alternatively, you can set environment variables instead of using a configuration file. This approach works well for CI/CD environments:

Environment Variables
export GRANTFLOW_API_URL="https://api.grantflow.cloud"
export GRANTFLOW_TENANT_ID="your-azure-tenant-id"
export GRANTFLOW_CLIENT_ID="your-grantflow-client-id"
export GRANTFLOW_OUTPUT="table"

Add these lines to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make them permanent.

Command-Line Flags​

For one-off commands or testing, you can provide configuration directly via flags:

Command-Line Flags
grantflow roles list \
--api-url "https://api.grantflow.cloud" \
--tenant-id "your-azure-tenant-id" \
--client-id "your-grantflow-client-id"

Configuration Precedence​

The CLI uses the following precedence order when loading configuration:

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Configuration file
  4. Default values (lowest priority)

This allows you to set defaults in your config file while overriding specific values when needed.

Authentication​

Once configured, authenticate with your Azure Entra ID account:

Authentication
grantflow login

The CLI will display a device code and verification URL. Open the URL in your browser, enter the code, and complete the sign-in process. The CLI will automatically cache your token for future requests.

To sign in, use a web browser to open the page:
  https://microsoft.com/devicelogin

Enter the code: ABC123XYZ

Waiting for you to complete authentication...

✓ Authentication successful!
note

Tokens are cached in ~/.grantflow/token-cache.json with restrictive permissions (mode 0600) to protect your credentials.

Verify Configuration​

Confirm your configuration is working by listing available roles:

Verify Configuration
grantflow roles list

If you see a table of roles, you're ready to use the CLI. If you encounter errors, see the Troubleshooting guide.

Next Steps​

Now that you're set up, explore the CLI's capabilities:

Updating the CLI​

To update to the latest version, use your package manager:

Update CLI
# macOS (Homebrew)
brew upgrade grantflow

# Windows (winget)
winget upgrade GrantFlow.CLI

# Manual update (all platforms)
# Once download.grantflow.cloud is available, download the latest binary and replace the existing one

Uninstallation​

If you need to remove the CLI:

Uninstall CLI
# macOS (Homebrew)
brew uninstall grantflow

# Windows (winget)
winget uninstall GrantFlow.CLI

# Manual removal
sudo rm /usr/local/bin/grantflow
rm -rf ~/.grantflow

This removes the CLI binary and all cached configuration and tokens.

Last updated on