How Agent Reach's uninstall --keep-config Flag Preserves Tokens While Removing Skill Files

The --keep-config flag in Agent Reach gates deletion of the ~/.agent-reach directory so tokens and API keys survive, while the uninstaller unconditionally removes skill files from OpenClaw, Claude Code, and generic agent directories.

When working with the Panniantong/Agent-Reach CLI, the uninstall --keep-config command lets you purge deployed skills without losing your stored credentials. This behavior is controlled by two independent cleanup phases in agent_reach/cli.py: one gated by the keep_config boolean and another that always iterates over skill directories. Understanding this separation ensures you can safely uninstall heavy-weight components while retaining your API tokens and cookies.

Where Agent Reach Stores Tokens and Configuration

The Config class persists all sensitive data to the local filesystem. As implemented in agent_reach/config.py, tokens, cookies, and API keys are written to ~/.agent-reach/config.yaml, making the ~/.agent-reach directory the single source of truth for user configuration. Because this directory is separate from the skill installation paths, the uninstaller can target one without affecting the other.

The Config Directory

The ~/.agent-reach directory serves as the central storage for authentication state and user preferences. The Config class handles all reads and writes to config.yaml inside this folder. Uninstall operations interact with this directory directly, not with the skill files that are scattered across platform-specific paths.

How the --keep-config Flag Gates Directory Removal

In agent_reach/cli.py (lines 1329–1357), the uninstall routine evaluates the keep_config boolean before touching the filesystem. If the flag is absent, the code removes the configuration directory with shutil.rmtree; if present, it skips the deletion entirely. This single conditional is what keeps your tokens intact while the rest of the cleanup proceeds.

Conditional Config Deletion

The following excerpt from agent_reach/cli.py shows the conditional guard that protects your credentials:

# agent_reach/cli.py (uninstall logic)

if not keep_config:
    if os.path.isdir(config_dir):
        ...
        shutil.rmtree(config_dir)          # ← removes tokens

    else:
        print(f"  Config directory not found: {config_dir}")
else:
    print(f"  Skipping config directory (--keep-config): {config_dir}")

Source: agent_reach/cli.py lines 1329–1357.

This logic runs during the uninstall routine and is the only barrier between your tokens and deletion.

Why Skill Files Are Removed Unconditionally

Skill registration is completely independent of the configuration directory. The installation routines _install_skill and _uninstall_skill in agent_reach/cli.py (around lines 2244–2366) establish the platform-specific paths, and the uninstaller mirrors them exactly during cleanup. Even when --keep-config is passed, the skill cleanup phase always executes.

The Skill Removal Loop

The following excerpt from agent_reach/cli.py (lines 1359–1374) shows the unconditional skill purge:

# agent_reach/cli.py (skill removal)

skill_dirs = [
    ("~/.openclaw/skills/agent-reach", "OpenClaw"),
    ("~/.claude/skills/agent-reach", "Claude Code"),
    ("~/.agents/skills/agent-reach", "Agent"),
]
for skill_path_template, platform_name in skill_dirs:
    skill_path = os.path.expanduser(skill_path_template)
    if os.path.isdir(skill_path):
        if dry_run:
            print(f"[dry-run] Would remove {platform_name} skill: {skill_path}")
        else:
            shutil.rmtree(skill_path)
            print(f"  Removed {platform_name} skill: {skill_path}")

Notice that the loop inspects dry_run but never checks keep_config. This guarantees that any installed SKILL.md files and related skill assets are removed even while your authentication tokens remain safe in ~/.agent-reach.

Practical Uninstall Commands

You can run the uninstaller with different flag combinations depending on whether you want to preserve credentials, preview changes, or perform a full wipe. The --dry-run option is available for all variations and prints the intended actions without modifying the filesystem. Combining it with --keep-config is the safest way to verify exactly what will be deleted before you commit to the operation.

Preview Changes with --dry-run

# Show actions without deleting anything

agent-reach uninstall --keep-config --dry-run

With both flags set, the CLI emits a preview showing that ~/.agent-reach is skipped while the three skill directories are slated for removal. You can verify token safety before any deletion occurs.

Common Command Combinations

These patterns cover the typical uninstall scenarios for Agent Reach. Choose the combination that matches whether you want to preserve credentials, preview changes, or fully reset the tool.

• agent-reach uninstall – Deletes ~/.agent-reach (tokens) and all registered skill files.
• agent-reach uninstall --keep-config – Preserves ~/.agent-reach and its tokens, but removes all skill files.
• agent-reach uninstall --dry-run – Prints every planned deletion without touching the filesystem.
• agent-reach uninstall --keep-config --dry-run – Prints a preview showing the config directory is kept while skill files would be removed.

Summary

• The --keep-config flag only skips deletion of ~/.agent-reach, preserving tokens, cookies, and API keys stored in config.yaml.
• Skill files are always removed because they reside in platform-specific paths that the uninstaller cleans unconditionally.
• The two-phase cleanup in agent_reach/cli.py separates authentication storage from skill deployment, allowing precise uninstall control.
• Use --dry-run to preview deletions without risk.

Frequently Asked Questions

What directory stores Agent Reach tokens and configuration?

Agent Reach persists all tokens, cookies, and API keys to ~/.agent-reach/config.yaml, managed by the Config class in agent_reach/config.py. When you run the uninstaller without --keep-config, it deletes the entire ~/.agent-reach directory, which removes those credentials permanently.

Does --keep-config prevent skill files from being removed?

No. The --keep-config flag only gates the removal of the configuration directory. Because skill files live under ~/.openclaw/skills/agent-reach, ~/.claude/skills/agent-reach, and ~/.agents/skills/agent-reach, the uninstaller always targets them independently in the cleanup loop found at lines 1359–1374 of agent_reach/cli.py.

Can I preview what the uninstaller will delete before running it?

Yes. Append the --dry-run flag to any uninstall command. The CLI will list every intended removal — including which skill directories would be deleted and whether the config directory is skipped — without invoking shutil.rmtree on your filesystem.

Where are Agent Reach skill files installed?

According to the Panniantong/Agent-Reach source code, skills are placed in ~/.openclaw/skills/agent-reach for OpenClaw, ~/.claude/skills/agent-reach for Claude Code, and ~/.agents/skills/agent-reach for generic agents. Both the installation helper and the uninstall loop in agent_reach/cli.py reference these exact paths, which is why they are always removed during uninstallation regardless of the --keep-config setting.

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