# xiaohongshu-cli: a Python CLI for Xiaohongshu search, reading and posting

> jackwener/xiaohongshu-cli wraps Xiaohongshu's reverse-engineered web API in a single xhs command with YAML or JSON output. It suits scripted scraping and agent pipelines, not anyone who needs a stable, sanctioned interface.

**jackwener/xiaohongshu-cli** — A CLI for Xiaohongshu (小红书) — search, read, interact via reverse-engineered API

- Repository: https://github.com/jackwener/xiaohongshu-cli
- Stars: 2,625 · Forks: 274
- Language: Python
- License: not declared
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/jackwener-xiaohongshu-cli

## Who xiaohongshu-cli is for

Xiaohongshu has no public, documented developer API for the operations this tool performs. xiaohongshu-cli fills that gap by driving the same endpoints the web client uses and exposing them as subcommands. The README describes it as a CLI for search, reading, interaction and posting via a reverse-engineered API, and the PyPI metadata classifies it as Development Status 3 - Alpha.

The audience is narrow and specific. If you are building a data pipeline that pulls note text, comments and user profiles on a schedule, or wiring an AI agent to a shell command that returns structured output, the shape fits. The README even carries an AI Agent Tip recommending --yaml unless strict JSON is required. If you are a product team looking for a supported integration with a service level agreement, this is the wrong layer: the contract is whatever the web client currently sends.

## How the xhs command reaches Xiaohongshu

The package installs a console script named xhs, mapped in pyproject.toml to xhs_cli.cli:cli, so the CLI is a thin Click layer over a Python client built on httpx. Authentication is the interesting part. Rather than an OAuth flow, it extracts cookies from a local browser through browser-cookie3, or falls back to a QR login that the README describes as browser-assisted, with the code scanned in the terminal. The camoufox and xhshow dependencies point at the signing and fingerprinting side of the request path.

Requests are shaped to look like a consistent macOS Chrome client. The feature list names a stable browser identity per session, sec-ch-ua alignment, Gaussian jitter on timing, a captcha cooldown and exponential backoff. Those are mitigations against rate limiting and bot detection, not guarantees. Because the tool reuses the web API, every command inherits the same fragility: when Xiaohongshu changes request signing or response shape, the CLI has to catch up.

Output has a deliberate contract. Commands accept --json or --yaml, and the README states that non-TTY stdout defaults to YAML, which is what makes the tool usable inside a pipeline without passing flags. The envelope is documented in SCHEMA.md as ok, schema_version, data and error. That schema_version field is the part worth designing around.

## Installing xiaohongshu-cli and reading your first note

The README recommends uv tool for an isolated install, with pipx as the alternative. Python 3.10 or newer is required according to pyproject.toml. Both commands below are copied from the README's installation section.

```bash
uv tool install xiaohongshu-cli
# Or: pipx install xiaohongshu-cli
```

After installation the xhs command should be on your PATH. The next step is authentication. The README offers two paths: cookie extraction from your browser, or a QR login.

```bash
xhs login
xhs status
```

The first command extracts cookies from the browser; the second reports whether the session is usable. If cookie extraction fails, the README gives a QR variant that it describes as browser-assisted, with the code scanned in the terminal.

```bash
xhs login --qrcode
```

With a session in place, a search followed by a short-index read is the quickest way to see the data shape. The README documents that list commands such as search, feed, hot, user-posts, favorites and my-notes set a short index, which later commands address by position.

```bash
xhs search "美食" --sort popular
xhs read 1
xhs comments 1 --all --json
```

The first line searches notes sorted by popularity. The second reads the first result from that listing. The third fetches every comment page for the same note and emits JSON, which is the form you want if another program is consuming it. Note that the README recommends upgrading regularly, on the grounds that outdated API handling causes unexpected errors.

```bash
uv tool upgrade xiaohongshu-cli
```

## Where the reverse-engineered API breaks down

The central limitation is stated by the project itself: the API is reverse-engineered. Nothing in the repository pins a version of the upstream service, and the README's advice to upgrade regularly is an admission that the client tracks a moving target. A release that worked last month can return errors after a server-side change, and the fix arrives only when a new version ships.

Authentication is the second weak point. Cookie extraction depends on how your browser stores cookies and on being logged in there; the QR path depends on camoufox driving a browser. Neither is a credential you can rotate cleanly in CI, and neither is documented with a refresh story. If your environment has no browser and no way to complete an interactive scan, the login step is a wall.

The third constraint is scope. Comment pagination is exposed through --all, but the README does not document rate limits, retry budgets or what happens when the backoff exhausts. A long crawl is therefore an unknown quantity. The tool is also a client for a consumer service, so volume that looks modest to you may look like abuse to the endpoint. Treat bulk reads as something to test carefully rather than assume.

## How it compares with Xiaohongshu-MCP and Bilibili-cli

The closest alternative in the related searches is Xiaohongshu-MCP, which takes a different architectural stance: instead of a shell command that a human or script invokes, it exposes Xiaohongshu operations as tools over the Model Context Protocol so an LLM client calls them directly. The practical difference is where the orchestration lives. With xiaohongshu-cli you compose commands, parse the envelope and manage state yourself; with an MCP server the model selects tools and the server holds the session. If your workflow is already an agent loop with MCP support, that integration is less glue. If you want deterministic, inspectable pipelines with shell history and exit codes, the CLI is the better fit.

The other comparison is the author's own bilibili-cli, listed in the README's More Tools section alongside twitter-cli, discord-cli and tg-cli. Those share the same design philosophy: a Python CLI over a platform's private endpoints, structured output, short-index navigation. Choosing among them is mostly about which platform you need, but the shared lineage is worth noting because it means the maintenance burden is spread across several projects rather than concentrated on one. The last push to this repository was on 2026-03-21, so the code has been quiet for several months; the upgrade advice in the README still applies, and there is no release history in the repository to show how quickly fixes have landed.

## Licence, upgrade cost and what the repository does not say

pyproject.toml declares license = "Apache-2.0" and carries the matching classifier, so the code is permissively licensed for commercial and private use. The repository's LICENSE file is not in the top-level listing, so the canonical text lives in the package metadata rather than an obvious file at the root. That is worth confirming if your legal review requires the file itself. Apache-2.0 covers the software; it says nothing about the terms under which Xiaohongshu permits access to its service, and the README does not discuss that boundary at all. That gap is the one to raise with whoever signs off on data collection.

Upgrade cost is low in mechanism and uncertain in cadence. The README gives uv tool upgrade and pipx upgrade, and from-source installs use uv sync. There are no pinned upstream API versions, so each upgrade is a small bet that endpoint handling improved rather than regressed. The dev extra adds pytest, pytest-asyncio, ruff and mypy, and the test configuration excludes smoke tests by default with addopts = "-m 'not smoke'", which means the real-API integration tests only run when invoked explicitly with pytest -m smoke. In other words, the default test run does not exercise the network path that breaks most often.

## Conclusion

Adopt it if you need scriptable Xiaohongshu reads, search or posting and can tolerate an alpha, Apache-2.0 project whose transport layer is a reverse-engineered API that can break without notice. Skip it if you need a sanctioned, contract-backed integration, or if you cannot accept that authentication depends on browser cookies and a QR login flow. Before relying on it, verify the login path on your own machine, check that the installed version matches the endpoint behavior you need, and read SCHEMA.md so your parser keys off schema_version rather than assuming the envelope is frozen.

## FAQ

### Is Xiaohongshu banned?

The README does not address availability or regional bans. It documents only how the CLI authenticates and which operations it exposes against Xiaohongshu's web endpoints.

### Is CLI a coding language?

No. In this project CLI stands for command line interface: xiaohongshu-cli is written in Python and installs an xhs command, not a language.

### What is CLI vs API?

Here the CLI is the xhs command you run, and the API is the reverse-engineered Xiaohongshu interface it calls behind the scenes. The README frames the project as a CLI for search, reading, interaction and posting via that reverse-engineered API.

## Sources

- [Issues](https://github.com/jackwener/xiaohongshu-cli/issues)
- [jackwener/xiaohongshu-cli on GitHub](https://github.com/jackwener/xiaohongshu-cli)
- [README](https://github.com/jackwener/xiaohongshu-cli/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jackwener-xiaohongshu-cli