How Environment Variables Override Config File Settings in Agent Reach

Agent Reach prioritizes uppercase environment variables over YAML file entries, allowing runtime overrides of any configuration key defined in ~/.agent-reach/config.yaml.

Agent Reach manages user preferences through a central configuration system that balances persistent storage with flexible runtime injection. The Config class in agent_reach/config.py implements a precedence-based lookup that ensures environment variables take priority over file-based settings, enabling secure credential management and temporary feature toggles without modifying the underlying YAML.

How the Override Mechanism Works

Lookup Order in Config.get()

The resolution logic resides in the Config.get() method at lines 75-84 of agent_reach/config.py. When retrieving a configuration value, the method follows this strict hierarchy:

1. Environment variables – The method converts the requested key to uppercase (e.g., groq_api_key becomes GROQ_API_KEY) and checks os.environ. If the variable exists, its value is returned immediately.
2. Configuration file – If the environment variable is absent, the method falls back to the loaded YAML data from ~/.agent-reach/config.yaml.
3. Default parameter – If neither source contains the key, the method returns the optional default argument or None.

This ordering ensures that setting a variable in your shell automatically overrides the corresponding entry in the persistent config file.

Case Sensitivity Convention

Environment variables conventionally use uppercase names. Agent Reach enforces this by automatically transforming configuration keys to uppercase before checking os.environ. This means a YAML entry groq_api_key is overridden by the environment variable GROQ_API_KEY, not groq_api_key.

Implementation Across the Codebase

Core Configuration Manager

In agent_reach/config.py, the Config class encapsulates all file I/O and environment variable resolution. The get() method handles the uppercase transformation internally, while is_configured() uses self.get(k) to verify that required keys are present—whether defined in the YAML file or supplied via environment variables.

CLI Feature Detection

The command-line interface in agent_reach/cli.py (lines 694-698) relies on this mechanism to detect API availability. When checking for a Groq API key, the CLI calls config.get(); if the user has exported GROQ_API_KEY in their shell, that value overrides any stale key stored in the YAML, preventing authentication errors.

Transcription Provider Integration

The transcription module in agent_reach/transcribe.py (specifically the _provider_key() helper at lines 7-10) retrieves provider credentials through config.get(field). This allows users to inject API keys via environment variables during batch processing without ever writing secrets to disk.

Practical Examples

Overriding API Keys at Runtime

To temporarily use a different API key than the one stored in your config file:

export GROQ_API_KEY="sk-env-override-789"
agent-reach transcribe https://example.com/podcast.mp3

Even if ~/.agent-reach/config.yaml contains groq_api_key: "file-key-123", the transcribe command uses sk-env-override-789 because Config.get() checks the environment first.

Python API Usage

from agent_reach.config import Config
import os

cfg = Config()

# Returns file value when env var is unset

print(cfg.get("groq_api_key"))  # → file-key-123

# Setting env var overrides subsequent calls

os.environ["GROQ_API_KEY"] = "runtime-key-456"
print(cfg.get("groq_api_key"))  # → runtime-key-456

Explicit Default Fallback

When a key is missing from both sources, provide a fallback:

# Returns "fallback-value" if neither file nor env provides the key

value = cfg.get("custom_endpoint", default="https://api.default.com")

Summary

• Configuration file location: ~/.agent-reach/config.yaml stores persistent settings.
• Override mechanism: The Config.get() method in agent_reach/config.py (lines 75-84) checks uppercase environment variables before reading the YAML file.
• Security benefit: API keys and secrets can be injected at runtime without modifying the persistent configuration.
• Broad application: Used in CLI argument parsing (agent_reach/cli.py), transcription providers (agent_reach/transcribe.py), and configuration validation throughout the codebase.

Frequently Asked Questions

What happens if both the config file and environment variable define the same key?

The environment variable takes precedence. Config.get() returns the value from os.environ immediately when the uppercase key exists, ignoring the YAML file entry.

Do I need to restart Agent Reach after setting an environment variable?

No. Config.get() performs a fresh lookup on each invocation, checking the current state of os.environ. Changes to environment variables reflect immediately in subsequent API calls or CLI commands.

Can I use lowercase environment variables?

No. Agent Reach automatically converts configuration keys to uppercase when querying the environment. To override groq_api_key, you must use GROQ_API_KEY in your shell.

What if the config file is missing entirely?

Agent Reach initializes with empty data if ~/.agent-reach/config.yaml is absent. In this scenario, Config.get() relies entirely on environment variables and defaults, making the system functional even without a persistent configuration file.

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