What Does Agent Reach Uninstall Remove and How Does the `--keep-config` Flag Work?

Running agent-reach uninstall deletes your local configuration directory, installed skill files, and MCP server entries, while the --keep-config flag preserves your credentials and settings by skipping the config directory removal.

The agent-reach uninstall command provides a clean way to remove Agent Reach artefacts from your system. According to the Panniantong/Agent-Reach repository, the private _cmd_uninstall() function in agent_reach/cli.py orchestrates a three-step cleanup process targeting specific paths and configurations. Understanding exactly what gets removed—and how the --keep-config option modifies this behavior—ensures you do not accidentally lose important credentials while cleaning up installation files.

What Agent Reach Uninstall Removes

When you execute agent-reach uninstall, the CLI targets three distinct categories of data for removal. The _cmd_uninstall() function in agent_reach/cli.py (lines 64–124) orchestrates this process sequentially.

Config Directory and Stored Credentials

The command first targets the ~/.agent-reach directory, which contains your config.yaml file. This file stores all sensitive user data including saved tokens, cookies, API keys, and proxy settings. Without the --keep-config flag, the entire directory is permanently deleted, erasing every configured credential and environment preference.

Skill Files and Symlinks

Next, the uninstaller removes skill installations from known agent directories. The code loops through specific paths including ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach. Whether these locations contain actual directories or symbolic links, the uninstaller deletes them entirely, removing the SKILL.md files and reference materials copied during installation.

MCP Server Entries

Finally, the command cleans up entries added to the MCP server via the mcporter tool. If the mcporter binary is present on your system, the uninstaller executes mcporter config remove for each registered entry—such as exa and xiaohongshu—effectively unregistering these tools from your MCP configuration.

How the --keep-config Option Affects Uninstallation

The --keep-config flag modifies the uninstall behavior by preserving your user data while still removing application files.

Without --keep-config: The CLI deletes the ~/.agent-reach directory completely, removing all stored tokens, cookies, and proxy configurations.

With --keep-config: The command skips the config directory removal step entirely. It prints "Skipping config directory (--keep-config)" and leaves ~/.agent-reach intact, preserving your credentials and settings. However, it still removes skill files and MCP entries, as the flag only affects step one of the three-step process.

Usage Examples

Run a full uninstall to remove everything including your configuration:

agent-reach uninstall

Preserve your credentials and settings while removing skills and MCP entries:

agent-reach uninstall --keep-config

Preview what would be removed without making changes:

agent-reach uninstall --dry-run

Combine flags to preview the action while preserving the config:

agent-reach uninstall --dry-run --keep-config

Summary

• The agent-reach uninstall command removes three categories of data: the ~/.agent-reach config directory, skill files from agent directories (~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach), and MCP server entries via mcporter.
• The _cmd_uninstall() function in agent_reach/cli.py handles this cleanup, targeting specific paths and invoking mcporter config remove for registered entries.
• The --keep-config flag skips deletion of the config directory, preserving your config.yaml and all stored credentials while still removing skill files and MCP entries.
• After execution, the CLI suggests manual cleanup of the Python package (pip uninstall agent-reach) and external tools, but does not execute these automatically.

Frequently Asked Questions

Does agent-reach uninstall remove the Python package itself?

No, the uninstall command does not remove the agent-reach Python package or the mcporter npm package. According to the source code in agent_reach/cli.py, the command only removes local configuration files, skill directories, and MCP entries. You must manually run pip uninstall agent-reach or npm uninstall -g mcporter to remove the actual binaries.

What happens if I run uninstall without --keep-config by mistake?

Without the --keep-config flag, the command permanently deletes your ~/.agent-reach directory containing config.yaml. This erases all saved tokens, API keys, cookies, and proxy settings. You will need to reconfigure these credentials by running the setup process again or restoring from a backup.

Why does --keep-config still remove MCP entries and skill files?

The --keep-config flag specifically targets only the configuration directory preservation step in the _cmd_uninstall() logic. The design separates user credentials (stored in ~/.agent-reach) from application artefacts (skills and MCP registrations). This allows you to clean up installed components while retaining your API keys and preferences for potential reinstallation.

Can I preview what will be removed before actually uninstalling?

Yes, use the --dry-run flag to see what the uninstaller would delete without making any changes. This shows the config directory, skill paths, and MCP entries that would be targeted, helping you decide whether to include --keep-config based on what credentials you want to preserve.

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