How the Agent-Reach Uninstall Command Handles the --keep-config Option

The --keep-config flag prevents the uninstall command from deleting the ~/.agent-reach directory, preserving your config.yaml, API keys, and stored credentials while removing all skill installations and mcporter entries.

The Agent-Reach CLI provides a comprehensive uninstall command to remove all software artefacts from your system. When you need to retain your configuration files and authentication tokens during removal, the --keep-config option offers a safe way to preserve sensitive data. This article examines exactly how the uninstall command processes this option according to the Panniantong/Agent-Reach source code.

Uninstall Implementation in agent_reach/cli.py

The uninstall logic resides in the _cmd_uninstall function within agent_reach/cli.py (lines 94-110). This function orchestrates the removal of three distinct components: the configuration directory, skill installations across various platforms, and mcporter registry entries.

Argument Parsing for --keep-config

The CLI uses argparse to handle the --keep-config flag. In lines 98-102 of agent_reach/cli.py, the argument is defined and parsed, storing the boolean value in a variable named keep_config:

# Conceptual representation based on source analysis

parser.add_argument('--keep-config', action='store_true', 
                    help='Retain the configuration directory')
args = parser.parse_args()
keep_config = args.keep_config

Conditional Configuration Directory Removal

The core logic that respects the --keep-config option appears in lines 102-105. The code checks if not keep_config: before executing the deletion:

• Without the flag: The code executes shutil.rmtree on ~/.agent-reach, permanently deleting config.yaml and all stored tokens.
• With the flag: The deletion is skipped, and the CLI outputs: Skipping config directory (--keep-config): /home/…/.agent-reach

What Gets Removed vs. Preserved

Understanding the scope of the uninstall command helps clarify the value of the --keep-config option.

Preserved Items (with --keep-config)

When you invoke agent-reach uninstall --keep-config, the following remain intact:

• The ~/.agent-reach directory structure
• config.yaml containing your settings
• All stored cookies, API keys, and authentication tokens
• User preferences and connection profiles

Removed Items (Always Deleted)

The following components are always deleted during uninstallation, regardless of the flag:

• OpenClaw skill installations (~/.openclaw/skills/agent-reach)
• Claude Code skill directories (~/.claude/skills/agent-reach)
• Generic Agent skill folders (~/.agents/skills/agent-reach)
• All mcporter registry entries (e.g., exa, xiaohongshu)

Practical Usage Examples

Complete Uninstallation

To remove Agent-Reach entirely, including all configuration and credentials:

agent-reach uninstall

This executes shutil.rmtree on the config directory and removes all skills and mcporter entries.

Preserving Configuration During Uninstall

To retain your settings for a future reinstall or migration:

agent-reach uninstall --keep-config

Expected output:

Agent Reach Uninstaller
========================================
  Skipping config directory (--keep-config): /home/username/.agent-reach
  Removed OpenClaw skill: /home/username/.openclaw/skills/agent-reach
  Removed Claude Code skill: /home/username/.claude/skills/agent-reach
  Removed Agent skill: /home/username/.agents/skills/agent-reach
  Removed mcporter entry: exa
  Removed mcporter entry: xiaohongshu

Key Files and Testing

The uninstall behavior is defined across several source files:

• agent_reach/cli.py: Contains the _cmd_uninstall function (lines 94-110) that implements the conditional deletion logic.
• agent_reach/config.py: Defines the ~/.agent-reach directory structure and configuration format that --keep-config protects.
• tests/test_cli.py: Validates the --keep-config flag behavior, ensuring the if not keep_config: branch correctly handles both scenarios.

Summary

• The --keep-config option in the Agent-Reach uninstall command preserves the ~/.agent-reach directory containing your config.yaml and credentials.
• The logic is implemented in _cmd_uninstall within agent_reach/cli.py (lines 94-110), specifically checking if not keep_config: before calling shutil.rmtree.
• Skill installations and mcporter entries are always removed regardless of the flag setting.
• The option is parsed via argparse and stored in the keep_config variable (lines 98-102).
• Use agent-reach uninstall --keep-config when you need to reinstall the software without reconfiguring API keys and preferences.

Frequently Asked Questions

Does --keep-config preserve my API keys and tokens?

Yes. The --keep-config option prevents the deletion of the entire ~/.agent-reach directory, which houses your config.yaml file along with all stored API keys, cookies, and authentication tokens. This is the primary use case for the flag—maintaining your credentials across uninstallation and reinstallation cycles.

What happens to skill installations when I use --keep-config?

Skill installations are always removed regardless of the --keep-config setting. The flag only affects the configuration directory. The uninstall command removes OpenClaw skills from ~/.openclaw/skills/agent-reach, Claude Code skills from ~/.claude/skills/agent-reach, and generic Agent skills from ~/.agents/skills/agent-reach as part of its standard cleanup routine in _cmd_uninstall.

Where is the --keep-config logic implemented in the source code?

The logic resides in the _cmd_uninstall function in agent_reach/cli.py, specifically between lines 94 and 110. The argument is defined in lines 98-102, and the conditional deletion logic appears in lines 102-105, where the code checks if not keep_config: before executing shutil.rmtree on the configuration path.

Can I reinstall Agent-Reach after using --keep-config without re-entering my credentials?

Yes. Since the --keep-config option preserves your config.yaml and authentication files in ~/.agent-reach, a subsequent installation will detect and reuse your existing configuration. You will not need to re-enter API keys or reconfigure your preferences, as the agent_reach/config.py module reads from the preserved directory.

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