# Agent Reach Uninstall Command and --keep-config Option Explained

> Learn how to uninstall Agent Reach with the uninstall command and preserve your configuration using the --keep-config option. Understand Agent Reach artifact removal and config persistence.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-14

---

**The `uninstall` command removes all Agent Reach artefacts, while the `--keep-config` flag preserves the `~/.agent-reach` directory containing your [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml), API keys, and authentication tokens.**

The Agent-Reach CLI provides utilities for managing AI agent configurations and skill installations. When you need to remove the software from your system, understanding the `uninstall` command and `--keep-config` option ensures you can either perform a total cleanup or retain your credentials for future reinstallation. These features are implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to give users precise control over data persistence.

## Core Implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)

The uninstall logic is contained within the `_cmd_uninstall` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 94-110). This handler coordinates the deletion of configuration files, skill directories, and mcporter registry entries.

### Argument Parsing

The command-line interface uses Python’s `argparse` module to detect the optional flag. The argument definition appears at lines 98-102, where `--keep-config` is registered as a boolean flag. When the user invokes the command, the parsed value is stored in the `keep_config` variable:

```python
keep_config = args.keep_config

```

### Conditional Directory Removal

The critical logic that respects the `--keep-config` option appears at lines 102-105. The code first checks `if not keep_config:` before attempting deletion:

- **Without the flag** (`keep_config` is `False`): The function removes the configuration directory using `shutil.rmtree`.
- **With the flag** (`keep_config` is `True`): The function skips the deletion and prints a confirmation message:

```text
Skipping config directory (--keep-config): /home/username/.agent-reach

```

## Complete Removal vs. Config Preservation

The `uninstall` command performs several cleanup actions, but their execution depends on the flag:

**Actions always performed:**
- Remove OpenClaw, Claude Code, and Agent skill directories
- Delete mcporter entries (e.g., `exa`, `xiaohongshu`)

**Actions conditional on `--keep-config`:**
- Deletion of the `~/.agent-reach` directory containing [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml), stored tokens, cookies, and API keys

If you omit the flag, the entire configuration directory is destroyed, requiring you to re-enter all credentials upon reinstallation. If you include the flag, your settings remain intact while the executable components and skills are purged.

## Practical Usage Examples

To perform a complete uninstall that deletes everything including your configuration:

```bash
agent-reach uninstall

```

To remove the software while keeping your configuration and credentials:

```bash
agent-reach uninstall --keep-config

```

Running the second command produces output similar to the following:

```text
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

```

## Supporting Components

- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Manages reading and writing of the configuration data stored under `~/.agent-reach` that the `--keep-config` option protects.
- **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)**: Contains test coverage verifying that the `_cmd_uninstall` function correctly interprets the `--keep-config` flag and conditionally preserves the configuration directory.

## Summary

- The `_cmd_uninstall` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 94-110) implements the removal logic.
- The `--keep-config` option parses at lines 98-102 and executes conditional logic at lines 102-105.
- Without the flag, `shutil.rmtree` deletes `~/.agent-reach` and its credentials.
- With the flag, the configuration directory is preserved while skills and mcporter entries are still removed.
- Use `--keep-config` when reinstalling later to avoid re-authenticating with API providers.

## Frequently Asked Questions

### What does the Agent Reach uninstall command remove by default?

By default, the command deletes the `~/.agent-reach` directory (including [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) and all stored tokens), removes skill installations from OpenClaw, Claude Code, and Agent directories, and clears all mcporter registry entries such as `exa` and `xiaohongshu`.

### When should I use the `--keep-config` option?

Use `--keep-config` when you plan to reinstall Agent Reach later and want to retain your API keys, authentication cookies, and settings, or when you need to preserve sensitive credentials while removing the software’s executable components and skills.

### Where is the uninstall logic implemented in the source code?

The logic resides in the `_cmd_uninstall` function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) between lines 94-110, with argument parsing defined at lines 98-102 and the conditional directory removal check at lines 102-105.

### Does `--keep-config` prevent removal of installed skills?

No. The `--keep-config` flag only protects the configuration directory and its contents. Skill directories and mcporter entries are always removed during the uninstallation process regardless of whether this option is present.