How Agent Reach Config System Handles YAML Environment Variable Overrides

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. 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:

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:

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:

# 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 – Houses the Config class with get, set, and delete methods that implement the YAML and environment variable resolution logic.
• 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 – 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 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, 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.

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