How to Uninstall Agent Reach While Preserving Configuration: Complete CLI Guide

To uninstall Agent Reach while preserving your configuration, run agent-reach uninstall --keep-config, which removes skill files and MCPorter entries but leaves the ~/.agent-reach directory containing your tokens and API keys intact.

Agent Reach provides a built-in uninstaller that automates cleanup across multiple directories and configuration files. The uninstallation logic resides in the _cmd_uninstall function within agent_reach/cli.py in the Panniantong/Agent-Reach repository, supporting both full removal and selective preservation of user data.

Understanding the Agent Reach Uninstaller

The uninstaller is implemented as a first-class CLI command rather than a manual cleanup script. When you execute agent-reach uninstall, the _cmd_uninstall function in agent_reach/cli.py orchestrates a four-step teardown process that targets specific installation artifacts while respecting flags like --keep-config and --dry-run.

This design ensures that configuration data stored in ~/.agent-reach/config.yaml—which contains sensitive information like tokens, cookies, and API keys—can be retained for future reinstallations while removing the functional components of the tool.

Step-by-Step Uninstallation Methods

Standard Uninstall (Full Removal)

To completely remove Agent Reach including all configuration data, execute the base uninstall command:

agent-reach uninstall

This command triggers the full cleanup sequence defined in lines 94-174 of agent_reach/cli.py, removing the configuration directory, skill file symlinks, and MCPorter backend entries.

Preserving Configuration with --keep-config

To uninstall Agent Reach while preserving configuration, append the --keep-config flag:

agent-reach uninstall --keep-config

According to the source code at lines 94-108 in agent_reach/cli.py, when --keep-config is present, the uninstaller skips the removal of the ~/.agent-reach directory. This preserves your config.yaml with all tokens, cookies, and API keys intact, allowing you to reinstall later without re-authenticating.

Previewing Changes with --dry-run

Before executing any destructive operations, verify what will be removed using the dry-run mode:

agent-reach uninstall --dry-run

This flag simulates the uninstallation process without modifying the filesystem, displaying which directories and entries would be deleted during a real run.

What Gets Removed During Uninstallation

The _cmd_uninstall function targets four distinct components, as implemented in agent_reach/cli.py:

Configuration Directory (~/.agent-reach)

By default, the uninstaller removes the entire ~/.agent-reach directory (lines 94-108), which houses the config.yaml file managed by agent_reach/config.py. This file stores user credentials and preferences. Unless --keep-config is specified, this directory is permanently deleted.

Skill File Symlinks

The uninstaller cleans up skill files located in agent-specific directories:

• ~/.openclaw/skills/agent-reach
• ~/.claude/skills/agent-reach
• ~/.agents/skills/agent-reach

As implemented in lines 112-132 of agent_reach/cli.py, these symlinks or directories—registered via agent_reach/skill/SKILL.md—are deleted unless running in dry-run mode.

MCPorter Configuration Entries

For users with mcporter installed, the uninstaller removes backend entries for Exa and Xiaohongshu from mcporter's configuration (lines 135-148). The code checks for existing mcporter installations and surgically removes only the Agent Reach-related entries without affecting other MCPorter configurations.

Summary Reporting and Manual Cleanup

Finally, the uninstaller prints a summary report (lines 155-174) reminding you to manually remove the Python package and any globally installed helper tools like mcporter, twitter-cli, or undici.

Complete Removal Commands

To fully purge Agent Reach from your system after running the CLI uninstaller, execute the following commands to remove the Python package and optional global dependencies:

# Remove the Python package itself

pip uninstall agent-reach

# Optional: Remove globally installed helper tools

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

These commands are referenced in the README's "🗑️ 卸载" section (lines 49-66) and ensure no residual executables remain in your environment.

Summary

• Use agent-reach uninstall --keep-config to remove Agent Reach while preserving your ~/.agent-reach configuration directory containing tokens and API keys
• The uninstaller is implemented in agent_reach/cli.py via the _cmd_uninstall function, which handles cleanup in four sequential steps
• Without flags, the uninstaller removes configuration files, skill symlinks from ~/.openclaw/skills/ and similar directories, and mcporter backend entries
• Always run with --dry-run first to preview destructive changes before applying them
• Follow up with pip uninstall agent-reach to remove the Python package itself after CLI cleanup

Frequently Asked Questions

How do I completely remove Agent Reach including the Python package?

First run agent-reach uninstall to clean up configuration and skill files, then execute pip uninstall agent-reach to remove the package from your Python environment. You may also need to manually remove global helper tools like mcporter or twitter-cli using npm or pipx.

Will uninstalling Agent Reach delete my API keys and tokens?

Only if you run the standard agent-reach uninstall command without the --keep-config flag. To preserve your credentials stored in ~/.agent-reach/config.yaml, always include the --keep-config flag, which instructs the _cmd_uninstall function to skip the configuration directory deletion (lines 94-108 in agent_reach/cli.py).

What is the difference between --dry-run and --keep-config?

The --dry-run flag simulates the uninstallation and prints what would be removed without actually deleting any files, allowing you to verify the scope of changes. The --keep-config flag performs a real uninstallation but specifically preserves the ~/.agent-reach directory while removing skill files and MCPorter entries. These flags can be combined to preview a configuration-preserving uninstall.

Where are the skill files located that get removed during uninstallation?

The uninstaller targets skill directories under three agent-specific paths: ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach. These locations are cleaned up during lines 112-132 of the uninstallation process in agent_reach/cli.py.

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