# How Agent Reach Config System Handles YAML Environment Variable Overrides

> Learn how the Agent Reach config system prioritizes YAML over environment variables. Discover fallback logic for overrides and ensure seamless configuration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-10

---

**Agent Reach prioritizes YAML configuration values over environment variables, checking the config file first and only falling back to uppercase environment variables when a key is absent.**

The Panniantong/Agent-Reach repository implements a hierarchical configuration system that balances persistent settings with runtime overrides. Understanding how the Agent Reach config system manages YAML environment variable overrides allows you to secure sensitive credentials while maintaining convenient CLI access. The system stores user-specific settings in `~/.agent-reach/config.yaml` and resolves values through a strict precedence-based lookup implemented in the `Config` class.

## Configuration Resolution Hierarchy

The configuration engine centers on the `Config` class defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When the library needs a setting, it invokes the `get` method, which implements a three-tier fallback system.

### The Config.get Method Logic

The resolution logic resides in the `get` method, which handles the YAML environment variable override behavior:

```python
def get(self, key: str, default: Any = None) -> Any:
    """Get a config value. Also checks environment variables (uppercase)."""
    # 1️⃣ Config file first

    if key in self.data:
        return self.data[key]

    # 2️⃣ Then env var (uppercase)

    env_val = os.environ.get(key.upper())
    if env_val:
        return env_val

    # 3️⃣ Fallback

    return default

```

### Precedence Rules

The lookup follows this deterministic order:

- **YAML values** take precedence when the key exists in `~/.agent-reach/config.yaml`, even if the value is an empty string.
- **Environment variables** act as a fallback, with the system searching for an uppercase version of the key name via `os.environ.get(key.upper())`.
- **Default parameters** return only when neither the YAML file nor the environment contains the requested key.

## Overriding YAML Settings with Environment Variables

Because YAML entries trump environment variables, you must explicitly clear the YAML key to activate environment variable overrides.

### Method 1: Remove the Key from config.yaml

Use the CLI to delete the entry entirely, allowing the system to fall back to environment variables:

```bash
agent-reach config delete exa_api_key
export EXA_API_KEY="env-secret"

```

### Method 2: Leave the Key Blank

Alternatively, you can set the YAML value to an empty string (e.g., `api_key: ""`), though the key must remain absent from the file for the environment variable to take precedence. To ensure reliable overrides, deletion is the recommended approach.

## Practical Implementation Example

This workflow demonstrates the Agent Reach config system YAML environment variable override capabilities:

```bash

# 1️⃣ Write a key to the YAML file (saved by the CLI)

agent-reach config set exa_api_key "yaml-secret"

# 2️⃣ Run a command – the library reads from YAML

agent-reach search "python tutorials"   # uses the yaml-secret

# 3️⃣ Override with an environment variable

export EXA_API_KEY="env-secret"
agent-reach search "python tutorials"   # still uses yaml-secret (YAML wins)

# 4️⃣ Remove the key from the YAML file to rely solely on env vars

agent-reach config delete exa_api_key
agent-reach search "python tutorials"   # now uses env-secret

```

> **Tip:** Store long-lived secrets in `~/.agent-reach/config.yaml` and short-lived or CI-time secrets as environment variables. This keeps credentials out of version-controlled files while allowing the CLI to locate them dynamically.

## Source Code Architecture

The configuration system spans three critical files in the repository:

- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Houses the `Config` class with `get`, `set`, and `delete` methods that implement the YAML and environment variable resolution logic.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Provides the user-facing commands `agent-reach config set` and `agent-reach config delete` that manipulate the YAML file directly.
- **[`tests/test_config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_config.py)** – Contains the test suite validating the precedence logic between file-based settings and environment variable fallbacks.

## Summary

- Agent Reach stores persistent configuration in `~/.agent-reach/config.yaml`.
- The `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) checks YAML values first, then searches for uppercase environment variables only if the key is missing from the file.
- To override a YAML setting with an environment variable, remove the key using `agent-reach config delete <key>` or ensure it is absent from the configuration file.
- Environment variable changes take effect immediately without restarting the application, as `Config.get` reads directly from `os.environ` on each invocation.

## Frequently Asked Questions

### How does Agent Reach prioritize between config.yaml and environment variables?

Agent Reach always checks the YAML file first. According to the implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `get` method returns the YAML value whenever the key exists in `self.data`, completely bypassing environment variable checks. Only absent keys trigger the fallback to `os.environ.get(key.upper())`.

### Can I override a YAML setting without deleting it from the config file?

No. Because the precedence logic returns the YAML value for any existing key, you must remove the entry from `~/.agent-reach/config.yaml` using `agent-reach config delete <key>` to force the system to read from environment variables. Leaving a blank value still counts as the key existing.

### Where does Agent Reach store its configuration file?

The configuration file is located at `~/.agent-reach/config.yaml` in the user's home directory. This path is loaded once during `Config` class initialization but environment variable lookups occur dynamically on each `get` call.

### Do environment variable changes require restarting the Agent Reach CLI?

No. Unlike the YAML file which is loaded at initialization, the `Config.get` method queries `os.environ` directly on every call. This means changes to environment variables are reflected immediately in subsequent operations without restarting the process.