# How to Update Agent-Reach While Preserving Configuration

> Easily update Agent-Reach without losing settings. Learn how pip install -e . preserves your config.yaml, API keys, and proxies.

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

---

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

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

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

```bash
agent-reach doctor

```

The doctor routine—implemented in **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

```

## How Configuration Persistence Works

The `Config` class in **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash

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

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