Authentication Commands ​

These commands manage your authentication session with the GrantFlow API. You'll use them to log in, view your configuration, and clear cached credentials when needed.

grantflow login ​

Authenticate with the GrantFlow API using your Azure Entra ID credentials. The CLI uses OAuth2 device code flow, which means you'll complete the sign-in process in your web browser rather than entering credentials at the command line.

Usage ​

bash
grantflow login

How It Works ​

When you run this command, the CLI requests a device code from Azure Entra ID and displays it along with a verification URL. Open the URL in your browser, enter the displayed code, and complete the authentication flow using your organization's sign-in process.

The CLI waits for you to complete authentication, then retrieves and caches an access token locally. Subsequent commands use this cached token automatically, refreshing it when it expires.

Example ​

bash
$ grantflow login
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 in your browser...

✓ Authentication successful!
✓ Token cached for future requests

Token Storage ​

The CLI stores your access token and refresh token in ~/.grantflow/token-cache.json with file permissions set to 0600 (readable only by your user account). This cache persists across CLI sessions, so you only need to log in once until the refresh token expires.

DANGER

Never share your token cache file or include it in version control. It contains credentials that grant access to your GrantFlow tenant.

Multi-Factor Authentication ​

If your organization requires MFA, you'll complete the additional verification step during the browser-based sign-in. The CLI waits patiently for you to finish all authentication challenges.

Token Refresh ​

Access tokens typically expire after one hour, but the CLI automatically refreshes them using your cached refresh token. You won't notice this happening—commands just work. Refresh tokens themselves usually last for 90 days, after which you'll need to run grantflow login again.

Troubleshooting ​

If authentication fails, verify that your tenant_id and client_id are configured correctly. You can view your current configuration with grantflow config view.

If you see network errors, check that you can reach https://login.microsoftonline.com from your network. Some corporate networks require proxy configuration.

grantflow logout ​

Clear your cached authentication tokens, ending your CLI session. This command removes the token cache file entirely.

Usage ​

bash
grantflow logout

When to Use ​

You should log out when you're finished using the CLI on a shared workstation, when switching between different GrantFlow tenants, or when troubleshooting authentication issues.

Example ​

bash
$ grantflow logout
✓ Successfully logged out

After logging out, you'll need to run grantflow login again before using other commands.

What Gets Deleted ​

This command removes ~/.grantflow/token-cache.json but preserves your configuration file (~/.grantflow/config.yaml). Your tenant settings remain intact.

grantflow config view ​

Display your current CLI configuration, showing the resolved values from all configuration sources.

Usage ​

bash
grantflow config view [--output table|json|yaml]

Parameters ​

  • --output - Output format (default: table)

Example ​

bash
$ grantflow config view
API_URL    https://api.grantflow.cloud
TENANT_ID  YOUR_TENANT_ID
CLIENT_ID  32654b34-df24-4a9b-9261-27f37a66bff9
OUTPUT     table
DEBUG      false

JSON Output ​

The JSON format is useful for programmatic access to configuration values:

bash
$ grantflow config view --output json
{
  "api_url": "https://api.grantflow.cloud",
  "tenant_id": "YOUR_TENANT_ID",
  "client_id": "32654b34-df24-4a9b-9261-27f37a66bff9",
  "output": "table",
  "debug": false
}

Configuration Sources ​

The displayed values reflect the final resolved configuration after merging all sources in precedence order:

  1. Command-line flags (highest priority)
  2. Environment variables (prefixed with GRANTFLOW_)
  3. Configuration file (~/.grantflow/config.yaml)
  4. Built-in defaults (lowest priority)

This command helps you understand which values are active when troubleshooting configuration issues.

TIP

Use grantflow config view --output yaml to generate a template configuration file you can save to ~/.grantflow/config.yaml.

Security Note ​

This command never displays cached tokens or other sensitive credentials. It only shows configuration metadata like API URLs and client IDs.