How to Migrate from Legacy xhs-cli to OpenCLI for Xiaohongshu

To migrate from the deprecated xhs-cli backend to OpenCLI for Xiaohongshu in Agent-Reach, install OpenCLI and its Chrome extension, then verify the health status; the XiaoHongShuChannel automatically selects OpenCLI as the active backend when available.

Agent-Reach manages Xiaohongshu (小红书) integrations through a cascading backend strategy designed to prioritize modern, zero-configuration tooling. If your current setup relies on the legacy xhs-cli package, migrating to OpenCLI eliminates manual credential management by reusing your existing Chrome browser session.

Why Migrate from xhs-cli to OpenCLI?

The original xhs-cli upstream ceased active maintenance in March 2026, with the original author moving development efforts to the OpenCLI project (24k+ stars), as noted in the repository documentation at README.md lines 311-313. Beyond sustainability, OpenCLI offers a zero-configuration architecture that detects and utilizes your existing desktop Chrome login state, removing the need to export cookies or manage authentication tokens manually.

How Backend Selection Works in Agent-Reach

The XiaoHongShuChannel class in agent_reach/channels/xiaohongshu.py implements a probing mechanism that evaluates backend candidates in a strict priority order: OpenCLI → xiaohongshu-mcp → xhs-cli (source lines 52-53).

When the channel initializes, the check() method (lines 70-85) interrogates each candidate:

1. OpenCLI probe: Validates that the OpenCLI daemon is running and the Chrome extension is installed or installable.
2. Fallback to xiaohongshu-mcp: Checks for the MCP server availability.
3. Legacy xhs-cli: Only activates if the previous backends fail health checks.

This cascading fallback ensures existing installations remain functional while preferring modern backends, as implemented in the error handling logic at lines 189-196.

Step-by-Step Migration Guide

Follow these steps to transition your Xiaohongshu integration from the legacy CLI to OpenCLI.

1. Install OpenCLI

Install the OpenCLI package using your preferred package manager. Agent-Reach’s installer uses the following commands, documented in docs/install.md lines 183-185:

# Using pipx (recommended)

pipx install opencli

# Or using npm

npm install -g @jackwener/opencli

2. Install the Chrome Extension

OpenCLI requires a browser extension to access your logged-in session. Navigate to the Chrome Web Store link and add the extension:

https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk

This step is mandatory for OpenCLI to bridge your authenticated browser state with the CLI tool, as detailed in docs/install.md lines 186-189.

3. Verify the Installation

Confirm that OpenCLI can communicate with the extension and daemon:

opencli doctor

You should see Extension: connected and Daemon: running. If the extension shows as disconnected but is installed, the first real command will initialize the connection, according to the status parsing logic in agent_reach/backends/opencli.py lines 8-15.

Alternatively, run Agent-Reach’s diagnostic tool:

agent-reach doctor

4. Confirm Automatic Backend Selection

No code changes are required in your agents. Once OpenCLI reports a healthy status, XiaoHongShuChannel automatically elevates it to the active backend. Verify the selection using JSON output:

agent-reach doctor --json

The active_backend field for xiaohongshu should display "OpenCLI", referencing the diagnostic output structuring in agent_reach/doctor.py lines 61-66.

5. Remove Legacy Dependencies (Optional)

Once you have confirmed OpenCLI is functioning as the primary backend, uninstall the deprecated package to clean up your environment:

pipx uninstall xiaohongshu-cli

# or

npm uninstall -g xiaohongshu-cli

The channel will continue operating normally because OpenCLI now occupies the primary position in the backend stack.

Summary

• Deprecation: The legacy xhs-cli stopped receiving updates in March 2026; OpenCLI is the maintained successor.
• Zero-config: OpenCLI leverages your existing Chrome session, eliminating manual authentication steps.
• Automatic failover: XiaoHongShuChannel probes backends in order (OpenCLI → xiaohongshu-mcp → xhs-cli) and activates the first healthy option.
• Key files: Backend logic resides in agent_reach/channels/xiaohongshu.py, OpenCLI detection in agent_reach/backends/opencli.py, and health verification in agent_reach/doctor.py.

Frequently Asked Questions

What happens if OpenCLI is not installed?

If OpenCLI is missing or unhealthy, XiaoHongShuChannel automatically falls back to xiaohongshu-mcp or the legacy xhs-cli backend, ensuring your agents remain operational. This fallback chain is hardcoded in agent_reach/channels/xiaohongshu.py lines 189-196.

Do I need to modify my agent code to use OpenCLI?

No. The migration requires no changes to your agent implementations. The channel abstraction handles backend selection transparently based on availability, as controlled by the check() method in agent_reach/channels/xiaohongshu.py lines 70-85.

How does OpenCLI authenticate without explicit credentials?

OpenCLI uses a Chrome extension to access your existing browser session cookies. When you are logged into Xiaohongshu in Chrome, the extension allows OpenCLI to reuse that authenticated state, providing seamless access without exporting tokens or passwords, as described in the installation documentation at docs/install.md lines 186-189.

Can I keep xhs-cli installed as a backup?

Yes. While OpenCLI takes precedence when healthy, keeping the legacy xhs-cli installed provides a safety net. If OpenCLI fails or is uninstalled, the system automatically degrades to the legacy backend without manual intervention.

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