# How to Uninstall Agent-Reach While Preserving Configuration for Reinstallation

> Uninstall Agent-Reach easily while preserving all configuration for a quick reinstallation. Learn the simple command to keep your tokens cookies and proxy settings safe.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

## How the Uninstaller Works

The uninstall logic resides in the `_cmd_uninstall` function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) ([lines 1321–1365](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1321)). 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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) stores cookies, API keys, and proxy settings) using `shutil.rmtree` ([lines 1339–1350](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1339)) unless `--keep-config` is supplied.
3. **Deletes skill files** installed for supported agents like OpenClaw, Claude Code, and generic `.agents` ([lines 1360–1375](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1360)).
4. **Cleans up mcporter MCP entries** (such as the free Exa search backend) if `mcporter` is present on the system ([lines 1378–1395](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1378)).

## 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.

```bash
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.

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) and all authentication data for reinstallation.

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:**

```bash

# 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.

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) ([line 1329](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1329)), configuration resides in `~/.agent-reach/` (expanded via `os.path.expanduser`). The [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py) module manages read/write operations for [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) within this directory.