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:
- Command-line flags - Override everything for a single command
- Environment variables - Useful for CI/CD and containerized environments
- Configuration file - Persistent defaults for interactive use
- 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:
grantflow roles list --config /path/to/custom-config.yaml
File Format
The configuration file uses YAML format with a simple key-value structure:
api_url: "https://api.grantflow.cloud"
tenant_id: "5abfdf65-694b-4c35-9b9b-e65af70c8306"
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:
# 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.
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.
tenant_id: "5abfdf65-694b-4c35-9b9b-e65af70c8306"
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.
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.
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.
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.
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:
export GRANTFLOW_API_URL="https://api.grantflow.cloud"
export GRANTFLOW_TENANT_ID="5abfdf65-694b-4c35-9b9b-e65af70c8306"
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:
# 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:
# 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:
# 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:
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:
# 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:
# 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:
# 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:
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:
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:
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:
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:
# 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:
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.
Related Topics
- Installation & Setup - Initial configuration during installation
- Authentication Commands - Managing authentication sessions
- Troubleshooting - Solving common configuration problems