Agent Reach Environment Variables: Complete Configuration Guide

Agent Reach reads API keys and CLI settings from shell environment variables, falling back to the ~/.agent-reach/config.yaml file only when variables are unset, with uppercase environment variables taking precedence over stored configuration values.

Agent Reach supports flexible configuration through environment variables, allowing sensitive credentials to be injected at runtime without persisting them to disk. This approach complements the YAML-based configuration system defined in agent_reach/config.py, enabling secure automation in CI/CD pipelines and containerized deployments. When both sources define the same key, the environment variable always wins.

Feature-Specific Environment Variables

Agent Reach recognizes dedicated uppercase environment variables for each integrated service. The FEATURE_REQUIREMENTS mapping in agent_reach/config.py defines these relationships, and channel implementations like agent_reach/channels/twitter.py consume them to authenticate with external APIs.

Service	Config Key	Environment Variable
Exa Search	exa_api_key	EXA_API_KEY
Twitter XReach	twitter_auth_token, twitter_ct0	TWITTER_AUTH_TOKEN, TWITTER_CT0
Groq Whisper	groq_api_key	GROQ_API_KEY
OpenAI Whisper	openai_api_key	OPENAI_API_KEY
GitHub Integration	github_token	GITHUB_TOKEN

Resolution Mechanism

When the CLI checks for a required key, it evaluates presence using boolean logic. For example, in agent_reach/cli.py and transcription modules like agent_reach/transcribe.py, the code performs:

has_key = bool(os.environ.get("GROQ_API_KEY")) or bool(config.get("groq_api_key"))

Similarly, agent_reach/channels/xiaoyuzhou.py checks GROQ_API_KEY to determine if Groq-based processing is available. If the environment variable returns a non-empty string, that value is used; otherwise, the system queries the configuration object.

Generic Environment Variables

Beyond API credentials, Agent Reach inspects standard environment variables to detect runtime context and adjust behavior accordingly:

• AGENT_REACH_LANG — Sets the preferred language for the CLI interface
• PYTEST_CURRENT_TEST — Internal flag indicating test execution mode (used during development)
• DISPLAY / WAYLAND_DISPLAY — Detects graphical display availability to determine color output formatting
• SSH_CONNECTION / SSH_CLIENT — Detects SSH sessions for terminal behavior adjustments

How Agent Reach Environment Variables Are Resolved

Understanding the precedence hierarchy prevents configuration conflicts when both files and shell variables are present.

Lookup Hierarchy

The Config class implements a two-tier lookup system:

1. Environment variables — Config.get(key) converts the key to uppercase and checks os.environ.get(key.upper())
2. YAML configuration — Falls back to values stored in ~/.agent-reach/config.yaml
3. Absent values — Returns None or triggers a feature-disabled warning

CLI Explicit Checks

While the Config class handles the generic lookup, specific commands in agent_reach/cli.py perform explicit os.environ.get() calls for certain keys. Regardless of the check location, the outcome is identical: environment variables override configuration file entries.

Practical Configuration Examples

Setting API Keys for Transcription

Export variables before invoking the CLI to avoid writing credentials to disk:

export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXX"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
agent-reach transcribe "https://example.com/audio.mp3"

The agent_reach/transcribe.py module will detect GROQ_API_KEY and route the request to Groq's Whisper API.

Configuring Twitter XReach

For Twitter automation features, both tokens are required:

export TWITTER_AUTH_TOKEN="your_auth_token"
export TWITTER_CT0="your_ct0_cookie"
agent-reach post --channel=twitter "Hello from Agent Reach"

These values are read by agent_reach/channels/twitter.py to authenticate requests.

Overriding Stored Configuration

Even if github_token exists in your YAML file, you can override it for a single session:

export GITHUB_TOKEN="ghp_emergency_override"
agent-reach github repo list

The explicit environment variable takes precedence over the stored value in agent_reach/config.py.

Multi-Service Installation

When running the installer with automatic environment detection:

export EXA_API_KEY="exa_xxxxxxxx"
export GROQ_API_KEY="gsk_xxxxxxxx"
export GITHUB_TOKEN="ghp_xxxxxxxx"
agent-reach install --env=auto

Summary

• Agent Reach recognizes six feature-specific environment variables: EXA_API_KEY, TWITTER_AUTH_TOKEN, TWITTER_CT0, GROQ_API_KEY, OPENAI_API_KEY, and GITHUB_TOKEN
• The Config class in agent_reach/config.py converts keys to uppercase and checks os.environ before reading from ~/.agent-reach/config.yaml
• Environment variables always override configuration file entries; explicit CLI checks in agent_reach/cli.py maintain this precedence
• Generic variables like AGENT_REACH_LANG and DISPLAY control CLI localization and output formatting
• Channel implementations in agent_reach/channels/ (including twitter.py and xiaoyuzhou.py) consume these variables to authenticate with external services

Frequently Asked Questions

Do environment variables override the config file in Agent Reach?

Yes. When the Config.get() method resolves a key, it first checks os.environ.get(key.upper()) before reading from the YAML store. Additionally, the CLI in agent_reach/cli.py performs explicit environment checks for certain features. If GROQ_API_KEY is set in your shell, it will always take precedence over a groq_api_key entry in ~/.agent-reach/config.yaml.

What happens if an environment variable is empty or unset?

Agent Reach uses boolean evaluation to validate configuration. If os.environ.get("GROQ_API_KEY") returns None or an empty string, the system treats the credential as absent and falls back to the configuration file or disables the feature. Only non-empty string values are considered valid API keys.

Can I use environment variables for all Agent Reach settings?

Environment variable support is currently implemented for the five major integrations listed in the FEATURE_REQUIREMENTS mapping: Exa Search, Twitter XReach, Groq Whisper, OpenAI Whisper, and GitHub. Other configuration options—such as UI preferences—must be set via the YAML file or command-line flags.

Where does Agent Reach store configuration when not using environment variables?

When using the Config.set() method or interactive setup commands, values are persisted to ~/.agent-reach/config.yaml. This file serves as the permanent configuration store, while environment variables provide temporary, session-based overrides that are never written to disk.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}