# How Environment Variables Override Config File Settings in Agent Reach

> Learn how Agent Reach prioritizes environment variables over config file settings. Override configuration keys at runtime for flexible control.

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

---

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

```bash
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

```python
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:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)), transcription providers ([`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.