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

> Easily migrate from legacy xhs-cli to OpenCLI for Xiaohongshu using Agent-Reach. Install OpenCLI, set up the Chrome extension, and verify its health. Start leveraging the new backend today.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) lines 183-185:

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) lines 186-189.

### 3. Verify the Installation

Confirm that OpenCLI can communicate with the extension and daemon:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) lines 8-15.

Alternatively, run Agent-Reach’s diagnostic tool:

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

```bash
agent-reach doctor --json

```

The `active_backend` field for **xiaohongshu** should display `"OpenCLI"`, referencing the diagnostic output structuring in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), OpenCLI detection in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py), and health verification in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.