Configuration Guide ​

The GrantFlow CLI offers flexible configuration options to fit different workflows and environments. You can configure the CLI using a YAML file, environment variables, or command-line flags, with each method suitable for different scenarios.

Configuration Methods ​

The CLI loads configuration from multiple sources and merges them using a clear precedence hierarchy. This design lets you set defaults in a configuration file while overriding specific values for individual commands or environments.

Precedence Order ​

Configuration values are resolved in the following order, from highest to lowest priority:

  1. Command-line flags - Override everything for a single command
  2. Environment variables - Useful for CI/CD and containerized environments
  3. Configuration file - Persistent defaults for interactive use
  4. Built-in defaults - Fallback values when nothing else is specified

This means a command-line flag always wins, even if you've set the same value in a configuration file or environment variable.

Configuration File ​

The configuration file provides persistent settings that apply to all CLI commands. This is the most convenient option for interactive terminal use.

File Location ​

The CLI looks for its configuration file at ~/.grantflow/config.yaml by default. You can use a different location by setting the --config flag on any command:

bash
grantflow roles list --config /path/to/custom-config.yaml

File Format ​

The configuration file uses YAML format with a simple key-value structure:

yaml
api_url: "https://api.grantflow.cloud"
tenant_id: "YOUR_TENANT_ID"
client_id: "32654b34-df24-4a9b-9261-27f37a66bff9"
scope: "api://06b7f2b0-c048-4243-80c4-60d0f1bce15e/user_impersonation"
output: "table"
debug: false

Creating the Configuration File ​

You can create the file manually or generate it from the current configuration:

bash
# Create the directory if it doesn't exist
mkdir -p ~/.grantflow

# Generate a template from current config
grantflow config view --output yaml > ~/.grantflow/config.yaml

# Edit with your preferred editor
nano ~/.grantflow/config.yaml

Configuration Values ​

Here are the available configuration options:

api_url ​

The base URL of your GrantFlow API instance. For GrantFlow's cloud service, use https://api.grantflow.cloud. Self-hosted installations use their own domain.

yaml
api_url: "https://api.grantflow.cloud"

tenant_id ​

Your Azure Entra ID tenant ID. This identifies which Azure AD tenant to use for authentication. Your GrantFlow administrator provides this value.

yaml
tenant_id: "YOUR_TENANT_ID"

client_id ​

The Azure AD application (client) ID for the GrantFlow CLI application. This identifies the CLI to Azure AD during authentication. Your administrator provides this value.

yaml
client_id: "32654b34-df24-4a9b-9261-27f37a66bff9"

scope ​

The OAuth2 scope to request during authentication. This controls what permissions the CLI has when accessing the GrantFlow API. The default scope grants full user access.

yaml
scope: "api://06b7f2b0-c048-4243-80c4-60d0f1bce15e/user_impersonation"

If you don't specify a scope, the CLI uses api://<client-id>/.default as the default.

output ​

The default output format for commands. Valid values are table, json, and yaml. Table format works best for interactive terminal use, while JSON suits automation and scripting.

yaml
output: "table"

You can override this for individual commands using the --output flag.

debug ​

Enable debug logging to see detailed information about API requests, authentication flow, and error details. This is helpful when troubleshooting issues.

yaml
debug: false

Set to true to enable debug output, or use the --debug flag on individual commands.

Environment Variables ​

Environment variables provide configuration without a file, making them ideal for CI/CD pipelines, containers, and temporary environments.

Variable Names ​

All configuration values can be set via environment variables by prefixing the setting name with GRANTFLOW_ and using uppercase:

bash
export GRANTFLOW_API_URL="https://api.grantflow.cloud"
export GRANTFLOW_TENANT_ID="YOUR_TENANT_ID"
export GRANTFLOW_CLIENT_ID="32654b34-df24-4a9b-9261-27f37a66bff9"
export GRANTFLOW_SCOPE="api://06b7f2b0-c048-4243-80c4-60d0f1bce15e/user_impersonation"
export GRANTFLOW_OUTPUT="json"
export GRANTFLOW_DEBUG="true"

Shell Profile Integration ​

For persistent environment variables in interactive shells, add the exports to your shell profile:

bash
# For bash
echo 'export GRANTFLOW_API_URL="https://api.grantflow.cloud"' >> ~/.bashrc
echo 'export GRANTFLOW_TENANT_ID="your-tenant-id"' >> ~/.bashrc

# For zsh
echo 'export GRANTFLOW_API_URL="https://api.grantflow.cloud"' >> ~/.zshrc
echo 'export GRANTFLOW_TENANT_ID="your-tenant-id"' >> ~/.zshrc

Reload your shell or run source ~/.bashrc (or ~/.zshrc) to apply the changes.

CI/CD Integration ​

In CI/CD systems, set environment variables through your pipeline configuration:

yaml
# GitHub Actions example
env:
  GRANTFLOW_API_URL: \${{ secrets.GRANTFLOW_API_URL }}
  GRANTFLOW_TENANT_ID: \${{ secrets.GRANTFLOW_TENANT_ID }}
  GRANTFLOW_CLIENT_ID: \${{ secrets.GRANTFLOW_CLIENT_ID }}

Store sensitive values like tenant and client IDs in your CI system's secret management rather than hardcoding them in configuration files.

Command-Line Flags ​

Command-line flags override all other configuration sources for a single command invocation. This is useful when you need to temporarily use different settings.

Global Flags ​

These flags work with any command:

bash
# Override API URL for one command
grantflow roles list --api-url "https://staging-api.grantflow.cloud"

# Use different tenant configuration
grantflow roles list \\
  --tenant-id "different-tenant-id" \\
  --client-id "different-client-id"

# Change output format
grantflow roles list --output json

# Enable debug logging
grantflow roles list --debug

Combining Flags ​

You can combine multiple flags to override several settings at once:

bash
grantflow roles list \\
  --api-url "https://dev-api.grantflow.cloud" \\
  --output json \\
  --debug

Multi-Tenant Configuration ​

If you work with multiple GrantFlow tenants, you can manage separate configuration files for each:

bash
# Production configuration
grantflow roles list --config ~/.grantflow/prod-config.yaml

# Staging configuration
grantflow roles list --config ~/.grantflow/staging-config.yaml

# Development configuration
grantflow roles list --config ~/.grantflow/dev-config.yaml

Consider creating shell aliases for frequently used configurations:

bash
# Add to ~/.bashrc or ~/.zshrc
alias gf-prod='grantflow --config ~/.grantflow/prod-config.yaml'
alias gf-staging='grantflow --config ~/.grantflow/staging-config.yaml'
alias gf-dev='grantflow --config ~/.grantflow/dev-config.yaml'

# Usage
gf-prod roles list
gf-staging activations list

Viewing Current Configuration ​

To see which configuration values are currently active, use the config view command:

bash
# Table format (default)
grantflow config view

# JSON format for programmatic access
grantflow config view --output json

# YAML format for configuration generation
grantflow config view --output yaml > my-config.yaml

This shows the resolved configuration after merging all sources, helping you understand what values the CLI is actually using.

Security Considerations ​

Your configuration contains information about your tenant and authentication setup. While it doesn't include passwords or tokens, you should still protect it appropriately.

File Permissions ​

Ensure your configuration file has restrictive permissions:

bash
chmod 600 ~/.grantflow/config.yaml

This makes the file readable and writable only by your user account.

Sensitive Values ​

Never commit configuration files containing real tenant IDs or client IDs to public version control. If you need to share configuration templates, use placeholders:

yaml
api_url: "https://api.grantflow.cloud"
tenant_id: "YOUR_TENANT_ID_HERE"
client_id: "YOUR_CLIENT_ID_HERE"

Environment Variables in CI/CD ​

When using environment variables in CI/CD systems, always store sensitive values in the platform's secret management system rather than hardcoding them in pipeline definitions.

Troubleshooting Configuration ​

If you're having trouble with configuration, these steps can help identify the issue.

Verify Configuration Loading ​

Use the config view command to confirm the CLI is loading your configuration correctly:

bash
grantflow config view --output json

Compare the output to what you expect. If values don't match, check the precedence order—a flag or environment variable might be overriding your config file.

Check File Location ​

Confirm the CLI can find your configuration file:

bash
ls -la ~/.grantflow/config.yaml

If the file doesn't exist, create it following the instructions earlier in this guide.

Validate YAML Syntax ​

Malformed YAML causes parsing errors. Use a YAML validator to check your configuration file syntax:

bash
# On macOS/Linux with Python
python3 -c "import yaml; yaml.safe_load(open('~/.grantflow/config.yaml'))"

If you see errors, fix the YAML syntax and try again.

Test with Flags ​

If you suspect the configuration file is the problem, bypass it temporarily using command-line flags:

bash
grantflow roles list \\
  --api-url "https://api.grantflow.cloud" \\
  --tenant-id "your-tenant-id" \\
  --client-id "your-client-id"

If this works but the config file doesn't, the issue is likely in the file format or values.