How to Uninstall Agent Reach While Keeping Configuration: Complete Guide

Run agent-reach uninstall --keep-config to remove Agent Reach while preserving your saved tokens, cookies, and API credentials stored in the ~/.agent-reach directory.

Agent Reach is an open-source automation framework hosted in the Panniantong/Agent-Reach repository. When you need to uninstall Agent Reach while keeping configuration data intact for future use, the built-in uninstaller provides specific flags that control exactly which files get deleted.

Where Agent Reach Stores Your Configuration

Agent Reach persists all sensitive settings and session data in a dedicated configuration directory. According to the source code in agent_reach/cli.py (lines 1329-1350), the uninstaller targets the ~/.agent-reach directory by default, which contains your config.yaml file with stored cookies, API keys, and proxy configurations.

The ~/.agent-reach Directory Structure

This directory serves as the central repository for your authentication tokens and environment-specific settings. When you invoke the uninstall command without the preservation flag, the code executes shutil.rmtree on this path, permanently erasing your configuration unless you specify otherwise.

How to Uninstall Agent Reach While Keeping Configuration

The agent-reach uninstall command accepts the --keep-config flag to protect your settings while removing the core application files. This flag is parsed at line 1321 in agent_reach/cli.py within the _cmd_uninstall function, preventing the deletion routine from touching the configuration directory.

Use these commands to control the uninstallation scope:

# Preview what would be removed without making changes

agent-reach uninstall --dry-run

# Standard uninstall (removes everything including config)

agent-reach uninstall

# Uninstall while keeping configuration

agent-reach uninstall --keep-config

Reinstalling After a Preserved Uninstall

If you plan to reinstall Agent Reach later, preserving your configuration allows you to skip re-authentication. After uninstalling with --keep-config, your ~/.agent-reach directory remains intact with all tokens and cookies:

# Uninstall but preserve configuration

agent-reach uninstall --keep-config

# Later reinstall - automatically detects existing config

agent-reach install --env=auto

How the Uninstaller Works Under the Hood

The uninstallation logic is implemented in agent_reach/cli.py between lines 1321-1400. The _cmd_uninstall function follows a specific sequence to ensure complete removal of application components while respecting the --keep-config and --dry-run flags.

Configuration Directory Handling

At line 1329, the code defines config_dir = os.path.expanduser("~/.agent-reach"). Unless args.keep_config evaluates to true, lines 1339-1350 execute shutil.rmtree(config_dir), recursively deleting the entire configuration folder and its contents.

Skill Files and MCP Cleanup

Beyond the configuration directory, the uninstaller removes skill files installed for supported agents (OpenClaw, Claude Code, and generic .agents) at lines 1360-1375. It also cleans up mcporter MCP entries, such as the free Exa search backend configuration, between lines 1378-1395.

Previewing Changes with --dry-run

Before committing to the uninstallation, you can preview exactly which files and resources will be removed. The --dry-run flag, detected alongside --keep-config in the argument parser at line 1321, simulates the deletion process without making actual changes.

agent-reach uninstall --dry-run

This outputs a concise summary of the directories and registrations that would be deleted, allowing you to verify the scope before proceeding.

Complete Post-Uninstall Cleanup

After running the Agent Reach uninstaller, you must manually remove the Python package itself and any globally-installed helper tools that were added separately.

Remove the core package:

pip uninstall agent-reach

Clean up optional global tools installed via npm or pipx:

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

Summary

• Agent Reach stores configuration in ~/.agent-reach, including tokens and API keys in config.yaml.
• Use agent-reach uninstall --keep-config to preserve your configuration while removing the application.
• The uninstaller logic resides in agent_reach/cli.py lines 1321-1400, using shutil.rmtree for directory removal.
• The --dry-run flag lets you preview deletions before execution.
• After uninstalling with --keep-config, you can reinstall later and automatically reuse your saved credentials.

Frequently Asked Questions

Where does Agent Reach store configuration files?

Agent Reach stores all configuration files, including config.yaml with your cookies, API keys, and proxy settings, in the ~/.agent-reach directory. This path is hardcoded in agent_reach/cli.py at line 1329 and expanded using os.path.expanduser to ensure cross-platform compatibility.

What happens if I uninstall without the --keep-config flag?

Without the --keep-config flag, the uninstaller executes shutil.rmtree on the ~/.agent-reach directory (lines 1339-1350 in agent_reach/cli.py), permanently deleting your saved tokens, cookies, and all configuration settings. It also removes skill registrations and mcporter MCP entries as part of the complete cleanup.

Can I reinstall Agent Reach and reuse my saved configuration?

Yes. If you uninstall using --keep-config, your ~/.agent-reach directory remains intact. When you subsequently run agent-reach install --env=auto, the installer detects the existing configuration directory and automatically reuses your saved cookies and tokens, bypassing the need to re-authenticate.

What are mcporter entries and why does the uninstaller remove them?

Mcporter entries are MCP (Model Context Protocol) configurations, such as the free Exa search backend, that Agent Reach registers with the mcporter tool. The uninstaller removes these between lines 1378-1395 in agent_reach/cli.py to ensure complete cleanup of tool integrations, even when preserving your main configuration with --keep-config.

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