How to Update Agent-Reach While Preserving Configuration

Agent-Reach stores all user settings in ~/.agent-reach/config.yaml, so updating the repository and reinstalling the package with pip install -e . preserves your API keys, proxies, and credentials because the CLI only modifies this file when explicitly running configure commands.

Updating the Panniantong/Agent-Reach CLI tool requires pulling new code and reinstalling the package, but you never need to worry about losing your API keys or proxy settings. The application isolates user-specific configuration from the source code, ensuring that a standard update workflow leaves your credentials intact. This guide explains how to update Agent-Reach while preserving configuration using the built-in Config class and safety checks.

Where Agent-Reach Stores Your Configuration

All user-specific settings—including API keys, proxy values, and cookies—live in a dedicated configuration file at ~/.agent-reach/config.yaml. The core logic that manages this file resides in the Config class defined in agent_reach/config.py.

Because the CLI never overwrites this file unless you explicitly call a configure command, normal repository updates keep existing settings intact. The configuration directory sits outside the source tree, which means git pull and pip install operations cannot touch your personal data.

Step-by-Step Update Workflow

Follow these four steps to update Agent-Reach while preserving configuration and verifying system health.

1. Pull the Latest Code

Fetch the newest version from the repository:

git checkout main
git pull origin main

2. Reinstall the Package

Run the developer install command to recompile entry-point scripts without touching the configuration directory:

pip install -e .

This command updates the installed package code but does not modify ~/.agent-reach/config.yaml or its parent directory.

3. Verify Configuration Health

Run the diagnostic tool to ensure all required credentials are still recognized:

agent-reach doctor

The doctor routine—implemented in agent_reach/doctor.py—calls Config.is_configured() to check each feature’s required keys against the loaded YAML. It automatically falls back to environment variables if specific keys are missing from the file.

4. (Optional) Update Specific Keys

If you need to add or rotate credentials after updating, use the configure command. This is the only operation that rewrites the configuration file:

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

How Configuration Persistence Works

The Config class in agent_reach/config.py implements several safeguards to prevent accidental data loss:

• Write Protection: The file is only rewritten when Config.set() or Config.delete() is called via the configure sub-command handled in agent_reach/cli.py. Standard package updates trigger neither operation.
• Automatic Migration: The class automatically maps legacy keys (e.g., twitter_xreach → twitter_auth_token) when loading the YAML, so old configurations remain compatible with new code versions.
• Sensitive Data Masking: When you call Config.to_dict(), sensitive values are masked, preventing accidental exposure in logs while preserving the underlying data in the file.
• Environment Fallback: If a key is missing from config.yaml, the system checks for corresponding environment variables before failing.

Clean Reinstall Without Losing Data

If you prefer a completely fresh installation while keeping your configuration:

# Remove the previously installed package (keeps config)

pip uninstall agent-reach -y

# Reinstall from the updated source

pip install -e .

Because ~/.agent-reach/config.yaml persists independently of the Python package directory, uninstalling and reinstalling leaves your settings untouched.

Summary

• Configuration location: All settings live in ~/.agent-reach/config.yaml, managed by the Config class in agent_reach/config.py.
• Safe update process: Run git pull followed by pip install -e . to update code without touching configuration files.
• Verification: Use agent-reach doctor to validate that credentials remain readable after updates via Config.is_configured().
• Controlled writes: Only agent-reach configure commands trigger writes to the YAML file, as routed through agent_reach/cli.py.
• Legacy support: The Config class automatically migrates old key names to new ones, eliminating manual migration steps.

Frequently Asked Questions

Will updating Agent-Reach delete my API keys?

No. Because Agent-Reach stores credentials in ~/.agent-reach/config.yaml outside the source directory, running git pull and pip install -e . only modifies code files. The CLI only overwrites the configuration when you explicitly run agent-reach configure commands that call Config.set().

Where is the Agent-Reach configuration file located?

The configuration file is located at ~/.agent-reach/config.yaml on your system. This path is hardcoded in the Config class within agent_reach/config.py and remains stable across all versions of the tool.

How do I back up my Agent-Reach configuration before updating?

Simply copy the YAML file to another location before updating:

cp ~/.agent-reach/config.yaml ~/agent-reach-config-backup.yaml

You can restore it later by copying it back, or the Config class will automatically recognize the keys when you run agent-reach doctor.

What happens if I rename configuration keys manually?

The Config class automatically handles legacy key mapping (such as twitter_xreach to twitter_auth_token) during the load process. Unless you manually create conflicting entries, the system migrates old keys transparently without requiring manual intervention.

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