# Agent Reach Environment Variables: Complete Configuration Guide

> Discover Agent Reach environment variables for seamless configuration. Learn how Agent Reach uses API keys and CLI settings, prioritizing variables over config files.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-14

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) defines these relationships, and channel implementations like [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and transcription modules like [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), the code performs:

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

```

Similarly, [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

### Multi-Service Installation

When running the installer with automatic environment detection:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py) and [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.