How to Update Agent Reach While Preserving Your User Configuration

Agent Reach provides a seamless update workflow that upgrades the package and dependencies while automatically preserving your YAML configurations, custom skill files, and channel backends without overwriting existing settings.

Updating the Agent Reach toolset from the Panniantong/Agent-Reach repository requires more than just bumping a version number. The codebase is designed to evolve without forcing users to recreate their personal settings, ensuring that your agent-reach check-update and agent-reach doctor commands work predictably across releases.

Check for Available Updates

Before initiating any changes, verify whether a newer release exists. The agent-reach check-update command queries the repository and reports the current installed version against the latest available.

agent-reach check-update

This command parses the version metadata defined in agent_reach/cli.py and compares it against the remote source, giving you a clear go/no-go signal before proceeding.

Step-by-Step Update Process

Upgrade the Core Package

Install the newest package using standard Python tooling. If you installed Agent Reach in a virtual environment via pip, use the --upgrade flag:

pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip

For pipx installations, which isolate the tool in its own environment, use the force flag to overwrite while keeping user data directories intact:

pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip

Refresh Upstream CLI Tools

Agent Reach relies on external channel-specific CLIs (Twitter, Bilibili, 小红书, yt-dlp, rdt-cli, and npm-based tools). The update process only upgrades tools you already have, leaving untouched any additional utilities you may have installed.

Use conditional checks to update only present binaries:

# Twitter CLI

which twitter >/dev/null && { pipx upgrade twitter-cli || uv tool upgrade twitter-cli; }

# Bilibili client

which bili >/dev/null && { pipx upgrade bilibili-cli || uv tool upgrade bilibili-cli; }

# Xiaohongshu (小红书)

which xhs >/dev/null && { pipx upgrade xiaohongshu-cli || uv tool upgrade xiaohongshu-cli; }

# YouTube downloader

which yt-dlp >/dev/null && { pipx upgrade yt-dlp || uv tool upgrade yt-dlp || pip install -U yt-dlp; }

# Reddit CLI (pinned to specific commit)

which rdt >/dev/null && \
    pipx install --force 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66'

Handle Backend Transitions

When new versions introduce modern backends like OpenCLI for platforms such as 小红书 or Reddit, the system preserves legacy implementations rather than removing them. In agent_reach/core.py, the routing logic automatically falls back to legacy backends when the new default cannot be used.

If you have not yet installed OpenCLI, the update may prompt you:

if ! which opencli >/dev/null; then
    echo "本次更新引入了 OpenCLI 后端，是否安装？"
    # After user consent:

    agent-reach install --channels opencli
fi

Retired backends remain functional in agent_reach/channels/base.py, ensuring contract stability across updates.

Validate with Doctor

Run the diagnostic suite to confirm that every channel is functional and that user-provided skill files remain unchanged:

# Show new version

agent-reach version

# Run diagnostic suite

agent-reach doctor

# Export machine-readable report if needed

agent-reach doctor --json > doctor.json

The diagnostic engine in agent_reach/doctor.py inspects channel health, configuration files, and installed tools. It reports the active backend for each multi-backend platform and confirms that custom settings in your YAML files were left untouched.

How Configuration Preservation Works

The safety guarantees come from specific architectural decisions in the source code:

• agent_reach/config.py handles user configuration (YAML files, environment variables) and ensures updates never overwrite custom settings. It merges new default values with existing user preferences rather than replacing files.
• agent_reach/core.py implements the backend selection logic that preserves legacy paths while enabling new ones.
• agent_reach/channels/base.py defines the abstract base class that all channel implementations inherit from, ensuring that interface contracts remain stable even as implementations change.

These components together make the update-while-preserving-configuration experience reliable and repeatable.

Summary

• Use agent-reach check-update to detect new versions before upgrading.
• Upgrade via pip install --upgrade or pipx install --force depending on your installation method.
• Refresh upstream CLI tools conditionally to avoid installing unwanted dependencies.
• Legacy backends remain available in agent_reach/core.py for automatic fallback when new defaults are unavailable.
• Run agent-reach doctor after updating to verify that all channels function and that your configuration files remain intact.

Frequently Asked Questions

Will updating Agent Reach overwrite my custom skill files?

No. The agent_reach/config.py module specifically handles user configuration by merging new defaults with existing YAML files and environment variables. The agent-reach doctor command reports that user-provided skill files were left unchanged, confirming that your custom automation scripts remain intact.

What happens if a backend is deprecated during an update?

Retired backends are not removed from your system. According to the implementation in agent_reach/core.py, Agent Reach automatically falls back to legacy backends when the new default (such as OpenCLI for 小红书 or Reddit) cannot be used. This ensures continuity even if you delay adopting new dependencies.

How do I update Agent Reach if I installed it with pipx?

Use the force install command: pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip. This overwrites the package while preserving the pipx-managed virtual environment's user data directories, keeping your configuration isolated and intact.

Why does the doctor report show unchanged skill files?

The agent_reach/doctor.py diagnostic engine specifically validates that user-provided skill files were left unchanged during the update process. This serves as verification that the configuration preservation logic in agent_reach/config.py functioned correctly, giving you confirmation that no manual restoration is required.

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