How to Uninstall Agent Reach with `--dry-run` and `--keep-config`: A Complete Guide

The Agent Reach uninstall command supports both --dry-run to preview deletions and --keep-config to preserve your ~/.agent-reach/config.yaml while removing skills and tools.

Agent Reach is a Python-based glue layer that gives AI agents read and search access to internet platforms like Twitter/X, Reddit, and YouTube. When you need to remove the toolset without losing your configuration, or want to preview what would be deleted, the uninstall subcommand provides granular control through specific flags. This guide explains how to use these options based on the actual implementation in the Panniantong/Agent-Reach repository.

What Gets Removed During Uninstallation

The agent-reach uninstall command performs a systematic cleanup of three component categories. According to the implementation in agent_reach/cli.py, specifically within the _cmd_uninstall function, the process targets:

• The Agent Reach home directory (~/.agent-reach/), which contains the config.yaml file and cached tools
• Skill directories under ~/.openclaw, ~/.claude, and ~/.agents that contain the optional OpenClaw and Claude skill files (SKILL.md)
• Platform-specific entries in mcporter for Exa and Xiaohongshu channels

Each removal step reports its actions to the terminal, making the process fully transparent even when running in simulation mode.

The Role of --dry-run and --keep-config

These two flags modify the default destructive behavior of the uninstaller:

--dry-run: Executes the uninstallation logic without actually deleting files. This mode prints every planned deletion to the console, allowing you to audit what would be removed before committing to the action.

--keep-config: Preserves the ~/.agent-reach/config.yaml file and the directory structure while removing skills and external tool entries. This is useful when reinstalling Agent Reach later without re-entering API tokens and proxy settings.

When combined, --dry-run --keep-config shows you exactly which skill directories would be removed while guaranteeing that your configuration remains untouched.

How to Use the Uninstall Command

Preview Deletions Without Removing Files

Run a dry-run to see what would be deleted:

python -m agent_reach.cli uninstall --dry-run

This prints a report of every file and directory that would be removed, including paths like ~/.agent-reach/ and skill directories under ~/.openclaw/, without actually deleting them.

Preserve Configuration While Removing Everything Else

To uninstall the tool while keeping your settings:

python -m agent_reach.cli uninstall --keep-config

This removes all installed skills and mcporter entries but leaves ~/.agent-reach/config.yaml intact for future use.

Combined Safety Preview

The recommended approach for safe uninstallation combines both flags:

python -m agent_reach.cli uninstall --dry-run --keep-config

This shows exactly which skill directories would be removed while guaranteeing that your configuration remains untouched.

Implementation Details from Source Code

The uninstall logic resides in agent_reach/cli.py within the _cmd_uninstall function. This handler orchestrates the removal process by:

1. Checking for the --dry-run flag and setting a simulation mode
2. Conditionally skipping ~/.agent-reach deletion when --keep-config is present
3. Iterating through skill directories (~/.openclaw, ~/.claude, ~/.agents) and removing SKILL.md files via internal helpers _install_skill and _uninstall_skill
4. Cleaning up mcporter entries for specific channels like Exa and Xiaohongshu

The configuration management in agent_reach/config.py handles the ~/.agent-reach/config.yaml path, which the uninstaller references when determining whether to preserve or delete user settings based on the --keep-config flag.

Summary

• Agent Reach uninstall removes tools, skills, and optionally configuration files from your system.
• --dry-run previews all deletions without executing them, providing a safety audit.
• --keep-config preserves your ~/.agent-reach/config.yaml while removing skills and external dependencies.
• The implementation in agent_reach/cli.py handles removal of skill directories under ~/.openclaw, ~/.claude, and ~/.agents, plus mcporter entries for specific platforms.
• Combining both flags allows you to verify the uninstall scope while protecting your API tokens and proxy settings.

Frequently Asked Questions

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

--dry-run simulates the uninstallation and prints what would be deleted without actually removing files. --keep-config performs the actual uninstallation but skips deletion of the ~/.agent-reach/config.yaml file and its directory. You can use --dry-run alone to preview, --keep-config alone to uninstall while saving settings, or both together to preview an uninstall that preserves configuration.

Where does Agent Reach store configuration files?

Agent Reach stores user-specific settings in ~/.agent-reach/config.yaml, as defined in agent_reach/config.py. This file contains API tokens, proxy settings, and platform cookies. When using --keep-config, this specific path is preserved while other directories like ~/.openclaw and ~/.claude are removed.

Will uninstalling remove the installed platform tools like twitter-cli?

The uninstaller removes mcporter entries for channels like Exa and Xiaohongshu, and deletes Agent Reach-specific skills. However, external tools such as twitter-cli or yt-dlp that were installed separately on your system are not automatically removed by the _cmd_uninstall function. You must uninstall those dependencies manually if desired.

Can I reinstall Agent Reach after using --keep-config?

Yes. Since --keep-config preserves your ~/.agent-reach/config.yaml file, you can reinstall Agent Reach using python -m agent_reach.cli install and your previous settings will remain available. This is useful for troubleshooting or upgrading to a new version without reconfiguring API tokens.

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