How to Uninstall Agent-Reach While Preserving Configuration for Reinstallation

Run agent-reach uninstall --keep-config to remove the tool while preserving all saved tokens, cookies, and proxy settings stored in ~/.agent-reach for a future reinstall.

The Panniantong/Agent-Reach repository ships a built-in uninstaller that removes every component the tool created—skill registrations, credential stores, and optional MCP tooling—while offering a specific flag to shield your configuration directory from deletion. This guide explains how to use the uninstall command and its flags based on the actual implementation in agent_reach/cli.py.

How the Uninstaller Works

The uninstall logic resides in the _cmd_uninstall function within agent_reach/cli.py (lines 1321–1365). When you execute the uninstall command, the tool performs the following operations:

1. Parses CLI flags (--dry-run and --keep-config) via args.dry_run and args.keep_config.
2. Removes the configuration directory at ~/.agent-reach (where config.yaml stores cookies, API keys, and proxy settings) using shutil.rmtree (lines 1339–1350) unless --keep-config is supplied.
3. Deletes skill files installed for supported agents like OpenClaw, Claude Code, and generic .agents (lines 1360–1375).
4. Cleans up mcporter MCP entries (such as the free Exa search backend) if mcporter is present on the system (lines 1378–1395).

Step-by-Step Uninstallation Methods

Preview Changes with Dry-Run Mode

Use the --dry-run flag to see exactly what the uninstaller would delete without making any changes. This reads the configuration directory path and lists skill files and MCP entries targeted for removal.

agent-reach uninstall --dry-run

Full Uninstallation (Remove Everything)

Execute a complete uninstall that deletes the ~/.agent-reach directory, all skill registrations, and mcporter entries. This erases saved cookies, tokens, and settings permanently.

agent-reach uninstall

Preserving Configuration with --keep-config

Add the --keep-config flag to retain the ~/.agent-reach directory while still removing skill files and MCP tooling. This preserves config.yaml and all authentication data for reinstallation.

agent-reach uninstall --keep-config

What Gets Deleted vs. Preserved

Understanding the distinction between package files and configuration data ensures you do not accidentally lose API keys or session cookies.

Items always removed (unless using --dry-run):

• Skill registration files for OpenClaw, Claude Code, and generic .agents agents
• MCP server entries (e.g., Exa search backend configurations in mcporter)
• Compiled bytecode and temporary runtime files

Items preserved when using --keep-config:

• The entire ~/.agent-reach/ directory tree
• config.yaml containing proxy settings, API keys, and user preferences
• Saved browser cookies and authentication tokens
• Custom user scripts or extensions stored in the config directory

Complete Cleanup and Reinstallation Workflow

After running the tool-specific uninstaller, you may need to remove the Python package itself and optional global helper tools.

Complete removal including the package:

# Preserve config but remove the tool

agent-reach uninstall --keep-config

# Remove the Python package

pip uninstall agent-reach

# Optional: remove globally installed helper tools

npm uninstall -g mcporter
pipx uninstall twitter-cli
npm uninstall -g undici  # Used for Node.js proxy support

Reinstalling with existing configuration:

Because the ~/.agent-reach directory remains intact, the installer detects existing credentials on the next run and reuses them automatically.

# Reinstall (detects existing ~/.agent-reach and loads saved tokens)

agent-reach install --env=auto

Key Source Files and Implementation Details

File	Role	Relevant Sections
agent_reach/cli.py	CLI entry point implementing the uninstall command with flag detection, directory removal, and cleanup logic.	_cmd_uninstall function (lines 1321–1400)
agent_reach/config.py	Handles reading and writing ~/.agent-reach/config.yaml, the primary storage for sensitive credentials.	config_path initialization and Config class
agent_reach/doctor.py	Provides diagnostic reporting to verify complete removal post-uninstall.	check_all and format_report functions

Summary

• Use --keep-config to preserve ~/.agent-reach/config.yaml and authentication data during uninstallation.
• Use --dry-run first to preview what the uninstaller will delete without executing changes.
• The uninstaller removes skill files and MCP entries regardless of the --keep-config flag.
• Reinstallation automatically detects and reuses existing configuration if the ~/.agent-reach directory remains.

Frequently Asked Questions

Will reinstalling Agent-Reach detect my old configuration automatically?

Yes. If you preserved the ~/.agent-reach directory using --keep-config, the installation command agent-reach install --env=auto will detect the existing folder and load saved cookies, tokens, and proxy settings without requiring re-authentication.

What exactly is preserved when using --keep-config?

The --keep-config flag shields the entire ~/.agent-reach directory from deletion. This includes the config.yaml file (which stores API keys, proxy configurations, and user preferences), saved browser cookies, and any custom extensions or scripts you added to that directory.

How do I completely remove all traces of Agent-Reach including configuration?

Run agent-reach uninstall without the --keep-config flag to delete the configuration directory, followed by pip uninstall agent-reach to remove the Python package. You may also need to manually remove global tools like mcporter, twitter-cli, or undici if installed separately.

Where does Agent-Reach store its configuration files?

According to agent_reach/cli.py (line 1329), configuration resides in ~/.agent-reach/ (expanded via os.path.expanduser). The config.py module manages read/write operations for config.yaml within this directory.

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