How to Update Agent Reach and Refresh Its Channel Dependencies

Update Agent Reach by running agent-reach check-update to verify a new version exists, upgrade the core package via pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip, then refresh each channel dependency using pipx upgrade or uv tool upgrade for tools like twitter-cli, bilibili-cli, and yt-dlp, and finally verify with agent-reach doctor.

Agent Reach is a lightweight routing layer that connects AI agents to third-party platform CLIs. Keeping the core package and its channel dependencies synchronized ensures reliable access to APIs like Twitter, Bilibili, Reddit, and YouTube. This guide walks through the official update workflow documented in the Panniantong/Agent-Reach repository.

Check for Available Updates

Before upgrading, verify whether a newer release exists using the built-in check command.

The CLI command agent-reach check-update queries the repository and reports if a newer version is available. This step prevents unnecessary reinstalls when the current installation is already current.

Upgrade the Core Agent Reach Package

The recommended method installs the latest main archive directly from GitHub.

For pipx installations (the default recommendation), use:

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

If you installed Agent Reach using standard pip, run:

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

This command pulls the latest code from the main branch and replaces the existing distribution. The logic for these upgrade paths is implemented in agent_reach/cli.py.

Refresh Channel Dependencies

Agent Reach relies on external CLIs for each platform. The update process probes for installed tools and upgrades them using the preferred package manager, as documented in docs/update.md.

Twitter, Bilibili, and XiaoHongShu

For these platforms, the update script checks for CLI presence and attempts upgrades via pipx or uv tool:

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

YouTube (yt-dlp)

The YouTube channel uses yt-dlp, which supports additional fallback methods:

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

Reddit (rdt-cli)

Reddit requires a specific pinned version from Git because PyPI releases lag behind:

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

This installs the exact commit hash specified in agent_reach/cli.py to ensure compatibility with the current routing layer.

Desktop Users and OpenCLI Migration

Starting with version 1.5.0, Agent Reach defaults to OpenCLI for XiaoHongShu and Reddit on desktop environments. OpenCLI reuses your existing browser session instead of standalone CLIs.

If OpenCLI is not present, install it once and complete the Chrome extension authorization:

agent-reach install --channels opencli

This prompts you to click the Chrome extension to establish the session. The routing layer automatically falls back to legacy CLIs if OpenCLI is unavailable, following the coexistence policy documented in docs/update.md.

Co-Existence Policy and Backward Compatibility

The update process never removes existing tools. Retired backends—such as the old yt-dlp Bilibili mode—remain installed and functional. The routing layer in agent_reach/channels/*.py selects the first working backend automatically, ensuring backward compatibility while prioritizing newer implementations.

Verify the Installation

After updating, confirm the new version and diagnose channel health:

agent-reach version
agent-reach doctor

The doctor command, implemented in agent_reach/doctor.py, runs diagnostics and displays a status report. Each channel shows ✅ for active or [!] for issues, along with the currently selected backend. The command also auto-syncs bundled skill files to match the new version.

The CLI then summarizes the update for the user, reporting the new core version, the number of active channels, the backend each multi-backend channel is using, and any required manual actions such as "click the Chrome extension" or "run xhs login".

Summary

• Run agent-reach check-update to verify a new version exists before upgrading
• Upgrade the core package using pipx install --force with the main archive URL from Panniantong/Agent-Reach
• Refresh channel CLIs using pipx upgrade or uv tool upgrade for twitter-cli, bilibili-cli, xiaohongshu-cli, and yt-dlp
• Install Reddit's rdt-cli from the specific git commit hash 5e4fb3720d5c174e976cd425ccc3b879d52cac66 to avoid PyPI lag
• Desktop users should install OpenCLI for XiaoHongShu and Reddit browser-session support
• Execute agent-reach doctor to validate the installation and identify remaining setup steps

Frequently Asked Questions

Can I update Agent Reach without pipx?

Yes. While pipx is the recommended installation method according to docs/update.md, you can update using standard pip with pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip. The channel dependencies can also be managed with uv tool or plain pip if pipx is unavailable.

Why does the Reddit CLI require a specific git commit?

The PyPI release of rdt-cli lags behind the development repository. Agent Reach pins commit 5e4fb3720d5c174e976cd425ccc3b879d52cac66 in agent_reach/cli.py to ensure you have the latest fixes and API compatibility. Installing from this specific hash guarantees the routing layer functions correctly.

What happens if I don't update the channel dependencies?

Outdated channel CLIs may fail authentication or return API errors when platforms change their endpoints. The agent-reach doctor command detects version mismatches and reports them as [!] warnings, but the core Agent Reach package will attempt to route requests anyway, potentially falling back to alternative backends if available.

Is OpenCLI mandatory for desktop users?

No. OpenCLI is optional but recommended for XiaoHongShu and Reddit as of version 1.5.0. If you skip OpenCLI installation, Agent Reach continues using the legacy CLI tools (xiaohongshu-cli and rdt-cli) as fallbacks. The routing layer automatically selects the first working backend it discovers.

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