How to Uninstall Agent Reach and Preserve Config: Complete CLI Guide

Run agent-reach uninstall --keep-config to remove the tool while retaining your saved tokens, cookies, and proxy settings stored in ~/.agent-reach.

Agent Reach stores all sensitive credentials—from API keys to agent cookies—inside the ~/.agent-reach directory, which agent_reach/config.py manages as config.yaml. When you need to remove the package but retain those settings for a future install, the repository's CLI includes a native uninstall flow that supports selective deletion. According to the Panniantong/Agent-Reach source code, the uninstall subcommand implemented in agent_reach/cli.py gives you precise control over what is erased.

How the Agent Reach Uninstaller Works

The uninstall logic lives in the _cmd_uninstall function inside agent_reach/cli.py (lines 1321–1400). When you invoke agent-reach uninstall, the parser checks for two optional flags:

• --dry-run — previews every file and registration that would be deleted without making changes.
• --keep-config — skips the removal of the ~/.agent-reach directory so your credentials survive the cleanup.

At line 1329, the code resolves the configuration directory:

config_dir = os.path.expanduser("~/.agent-reach")

Unless args.keep_config is true, lines 1339–1350 delete that directory with shutil.rmtree, which erases config.yaml along with any saved cookies or proxy settings. When the flag is present, that path is left untouched while the rest of the cleanup proceeds.

Uninstall Agent Reach and Preserve Config: Step-by-Step

Preview changes with --dry-run

Before removing anything, verify what the uninstaller plans to delete:

agent-reach uninstall --dry-run

This executes the logic in _cmd_uninstall without calling shutil.rmtree or removing skill files, letting you inspect the planned changes safely.

Run the preserved uninstall

To delete skills, MCP entries, and tooling while keeping your configuration intact:

agent-reach uninstall --keep-config

Because --keep-config is present, the ~/.agent-reach folder remains on disk with all tokens and cookies preserved. The command still removes agent skill files (lines 1360–1375) and cleans up optional mcporter MCP entries such as the Exa search backend (lines 1378–1395).

Perform a full uninstall without preserving configuration

If you want a clean slate, omit --keep-config:

agent-reach uninstall

This triggers shutil.rmtree on ~/.agent-reach, permanently deleting your config.yaml and all saved cookies and API keys.

Remove the Python package and global helpers

The CLI uninstaller does not remove the agent-reach Python package itself. After the preserved uninstall, finish the cleanup manually:

# Remove the core Python package

pip uninstall agent-reach

# Optional: remove globally-installed helper tools

npm uninstall -g mcporter
pipx uninstall twitter-cli
npm uninstall -g undici

What Gets Removed vs. What Gets Kept

Understanding the exact scope prevents accidental data loss:

• Deleted: Skill registrations for OpenClaw, Claude Code, and generic .agents profiles, plus any mcporter MCP configurations.
• Preserved: The entire ~/.agent-reach directory, including config.yaml, when you pass --keep-config.
• Deleted: The ~/.agent-reach directory if you omit --keep-config, because lines 1339–1350 execute shutil.rmtree(config_dir).

Reinstalling After Preserving Your Configuration

Because your settings remain inside ~/.agent-reach, reinstallation is seamless:

agent-reach uninstall --keep-config
agent-reach install --env=auto

When the installer detects the existing ~/.agent-reach folder, it reuses the saved credentials rather than prompting for new ones.

Verify a Clean Removal with the Doctor Tool

If you want to confirm that channels and registrations were fully cleared after uninstalling, inspect the system with the diagnostic commands in agent_reach/doctor.py. The check_all and format_report functions report the current state of agent channels and can expose leftover artifacts.

Summary

• The agent-reach uninstall command is implemented in agent_reach/cli.py inside the _cmd_uninstall function.
• Pass --keep-config to prevent the uninstaller from deleting ~/.agent-reach and its config.yaml.
• Pass --dry-run to preview deletions without altering your system.
• Skill files and mcporter MCP entries are always removed during uninstall, regardless of the config flag.
• You must run pip uninstall agent-reach separately to remove the Python package after the built-in uninstall finishes.

Frequently Asked Questions

Does agent-reach uninstall also remove the Python package?

No. The _cmd_uninstall routine only deletes files, directories, and registrations created by the tool itself. To fully remove the package from your environment, run pip uninstall agent-reach after the CLI uninstall completes.

Where does Agent Reach store my API keys and cookies?

Agent Reach stores all sensitive data in ~/.agent-reach/config.yaml, a path managed by agent_reach/config.py. This directory also holds cookies, proxy settings, and other local state.

Will a future install reuse my preserved configuration?

Yes. If you run agent-reach install --env=auto while ~/.agent-reach still exists, the installer detects the leftover folder and reuses the saved tokens and cookies automatically.

What happens if I omit --keep-config?

The uninstaller resolves ~/.agent-reach via os.path.expanduser and then invokes shutil.rmtree on that directory (lines 1339–1350). This permanently erases your configuration, credentials, and cookies unless you have external backups.

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