# How Environment Variables Override YAML Settings in Agent Reach Configuration

> Learn how environment variables override Agent Reach YAML settings when config keys are missing. Understand precedence and ensure correct configuration.

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

---

**Environment variables act as fallback values that override YAML settings in Agent Reach only when the configuration key is absent from the file, following a strict precedence where in-file definitions take priority over uppercase environment variables.**

Agent Reach stores user-specific configuration in `~/.agent-reach/config.yaml` and uses the `Config` class to resolve settings at runtime. Understanding how environment variables override YAML settings in Agent Reach configuration allows developers to securely inject secrets without persisting them to disk while maintaining default values in version-controlled files. The resolution logic implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) prioritizes YAML entries but seamlessly falls back to environment variables when keys are missing or explicitly cleared.

## Configuration Precedence in Agent Reach

The `Config` class implements a three-tier lookup system that determines whether a value comes from the YAML file, an environment variable, or a default parameter. When you call `Config.get(key)`, the method evaluates sources in strict order:

1. **YAML file values** – Checked first via `self.data[key]`
2. **Environment variables** – Checked second via `os.environ.get(key.upper())`
3. **Default fallback** – Returned only if neither source provides a value

This hierarchy means that **YAML settings always win** when a key exists in the configuration file, even if an environment variable with the same name is set. Environment variables only serve as fallback mechanisms or injection points for secrets that should not be written to the persistent configuration file.

## The Config.get Implementation

The precedence logic lives in the `get` method of the `Config` class within [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py):

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

```

Because the method checks `self.data` before querying `os.environ`, any value defined in `~/.agent-reach/config.yaml` masks corresponding environment variables. The environment variable name must match the uppercase form of the configuration key (e.g., `exa_api_key` in YAML matches `EXA_API_KEY` in the environment).

## How to Force Environment Variables to Override YAML

To make environment variables override existing YAML settings, you must ensure the key is absent from the in-memory configuration data. You have two approaches to achieve this:

**Remove the key entirely** from the configuration file using the CLI:

```bash
agent-reach config delete exa_api_key

```

**Leave the key blank** in the YAML file:

```yaml
exa_api_key: ""

```

Once the key is empty or deleted from the YAML file, `Config.get` will skip the first branch of the conditional and proceed to check `os.environ`, effectively allowing the environment variable to supply the value. Because `os.environ` is accessed fresh on every `get` call, changes to environment variables take effect immediately without restarting the application.

## Practical Configuration Workflow

Here is a complete workflow demonstrating how to switch between YAML-persisted secrets and environment-injected values:

```bash

# 1️⃣ Store a key in YAML (persisted to ~/.agent-reach/config.yaml)

agent-reach config set exa_api_key "yaml-secret"

# 2️⃣ Verify YAML takes precedence

agent-reach search "python tutorials"   # Uses "yaml-secret"

# 3️⃣ Export an environment variable (ignored while YAML key exists)

export EXA_API_KEY="env-secret"
agent-reach search "python tutorials"   # Still uses "yaml-secret"

# 4️⃣ Remove the YAML key to enable environment variable fallback

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

```

This pattern allows you to commit a template configuration file to version control while keeping production secrets in environment variables that override the base settings at runtime.

## Key Source Files

The configuration resolution system spans three critical files in the Panniantong/Agent-Reach repository:

- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Contains the `Config` class with the `get` method that implements the YAML-to-environment fallback logic
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Provides the command-line interface for `config set`, `config delete`, and other operations that manipulate the YAML file
- **[`tests/test_config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_config.py)** – Validates the precedence behavior, ensuring that file-based configuration correctly masks environment variables when present

## Summary

- **YAML precedence**: Values in `~/.agent-reach/config.yaml` always take priority over environment variables when the key exists in the file.
- **Environment fallback**: Uppercase environment variables (e.g., `EXA_API_KEY`) provide values only when the corresponding key is missing from YAML or explicitly deleted.
- **Runtime updates**: Because `Config.get` queries `os.environ` on every call, environment variable changes apply immediately without reloading the configuration object.
- **Security pattern**: Store long-lived development secrets in YAML and short-lived or CI-specific credentials as environment variables to keep sensitive data out of version control.

## Frequently Asked Questions

### How do I completely override a YAML value with an environment variable in Agent Reach?

To completely override a YAML value, you must first delete the key from the configuration file using `agent-reach config delete <key>` or leave it blank in `~/.agent-reach/config.yaml`. Once the key is absent from the YAML data, `Config.get` will fall back to checking the uppercase environment variable, allowing it to provide the effective value.

### Why is my environment variable not overriding the YAML setting?

Environment variables only serve as fallback values in Agent Reach. If the key exists in `~/.agent-reach/config.yaml` with any non-empty value, the `Config.get` method returns the YAML value immediately and never checks `os.environ`. The library intentionally prioritizes file-based configuration to ensure explicit user settings persist across sessions.

### What naming convention should I use for environment variables?

Agent Reach converts configuration keys to uppercase when checking environment variables. For a YAML key like `exa_api_key`, set an environment variable named `EXA_API_KEY`. The `Config.get` method calls `key.upper()` internally, so you must use the capitalized form for the fallback mechanism to recognize your variable.

### Can I change environment variables without restarting my Agent Reach application?

Yes. Because the `get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) queries `os.environ` fresh on every invocation, changes to environment variables take effect immediately on the next configuration lookup. There is no need to reload the `Config` object or restart the process, making this approach suitable for dynamic secret rotation in long-running applications.