A CLI for Xiaohongshu (小红书) — search, read, interact via reverse-engineered API
A CLI for Xiaohongshu (小红书) — search, read, interact via reverse-engineered API
A CLI for Xiaohongshu (小红书) — search, read, interact, and post via reverse-engineered API
xhs read 1 or xhs comments 1sec-ch-ua alignment, session-stable browser identity, Gaussian jitter, captcha cooldown, exponential backoff--yaml and --json; non-TTY stdout defaults to YAMLok/schema_version/data/errorAI Agent Tip: Prefer
--yamlfor structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically.
# Recommended: uv tool (fast, isolated)
uv tool install xiaohongshu-cli
# Or: pipx
pipx install xiaohongshu-cliUpgrade to the latest version:
uv tool upgrade xiaohongshu-cli
# Or: pipx upgrade xiaohongshu-cliTip: Upgrade regularly to avoid unexpected errors from outdated API handling.
From source:
git clone [email protected]:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync…xiaohongshu-cli supports multiple authentication methods:
~/.xiaohongshu-cli/cookies.jsonxhs login --qrcode)xhs login automatically tries all installed browsers and uses the first one with valid cookies.
Use --cookie-source <browser> to specify a browser explicitly, or --qrcode for browser-assisted QR login.
Other authenticated commands automatically retry once with fresh browser cookies when the saved session has expired.
Saved cookies are valid for 7 days by default. After that, the client automatically attempts to refresh from the browser. If browser extraction fails, the existing cookies are used with a warning.
After any listing command such as search, feed, hot, user-posts, favorites, or my-notes, the CLI stores the latest ordered note list in ~/.xiaohongshu-cli/index_cache.json.
xhs read <N> opens the Nth note from the latest listingxhs comments <N> opens comments for the Nth note from the latest listingxhs like <N>, xhs favorite <N>, xhs unfavorite <N>, xhs comment <N>, and xhs reply <N> reuse the same short index| Variable | Default | Description |
|---|---|---|
OUTPUT |
auto |
Output format: json, yaml, rich, or auto (→ YAML when non-TTY) |
xiaohongshu-cli includes comprehensive anti-risk-control measures designed to minimize detection:
sec-ch-ua, sec-ch-ua-platform, and fingerprint fields are all consistent (macOS Chrome 145)MacIntel platform — all matching a real macOS browserx-s / x-s-common / x-t signatures (reverse-engineered from web client)x-b3-traceid and x-xray-traceid for distributed tracing consistencyAll --json / --yaml output uses the shared envelope from SCHEMA.md:
ok: true
schema_version: "1"
data: { ... }When stdout is not a TTY (e.g., piped or invoked by an AI agent), output defaults to YAML.
Use OUTPUT=yaml|json|rich|auto to override.
xiaohongshu-cli ships with a SKILL.md that teaches AI agents how to use it.
npx skills add jackwener/xiaohongshu-cli| Flag | Description |
|---|---|
-g |
Install globally (user-level, shared across projects) |
-a claude-code |
Target a specific agent |
-y |
Non-interactive mode |
mkdir -p .agents/skills
git clone [email protected]:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
…# Install dependencies
uv sync
# Run tests
uv run pytest tests/ -v
# Unit tests only (no network)
uv run pytest tests/ -v --ignore=tests/test_integration.py -m "not smoke"
# Smoke tests (need cookies)
uv run pytest tests/ -v -m smoke
# Integration tests (need cookies)
uv run pytest tests/test_integration.py -v
# Lint
uv run ruff check .Q: NoCookieError: No 'a1' cookie found
xhs login (auto-detects browser) or xhs login --cookie-source <browser>Q: NeedVerifyError: Captcha required
XHS has triggered a captcha check. Open https://www.xiaohongshu.com/ in your browser, complete the captcha, then retry.
Q: IpBlockedError: IP blocked by XHS
Try a different network (e.g., mobile hotspot or VPN). XHS blocks IPs that make too many requests.
Q: SessionExpiredError: Session expired
Your cookies have expired. Run xhs login to refresh.
Q: Requests are slow
The built-in Gaussian jitter delay (~1-1.5s between requests) is intentional to mimic natural browsing and avoid triggering XHS's risk control. Aggressive request patterns may lead to captcha triggers or IP blocks.
--yaml / --json，非 TTY 默认输出 YAML# 推荐：uv tool（快速、隔离环境）
uv tool install xiaohongshu-cli
# 或者：pipx
pipx install xiaohongshu-cli升级到最新版本：
uv tool upgrade xiaohongshu-cli
# 或：pipx upgrade xiaohongshu-cli提示： 建议定期升级，避免因版本过旧导致的 API 调用异常。
从源码安装：
git clone [email protected]:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync…xiaohongshu-cli 支持多种认证方式：
~/.xiaohongshu-cli/cookies.json 加载xhs login --qrcode）Cookie 保存后有效期 7 天，超时后自动尝试从浏览器刷新。
xhs login 会自动尝试所有已安装浏览器，使用第一个有有效 Cookie 的浏览器。也可用 --cookie-source <browser> 指定浏览器，或 --qrcode 使用 browser-assisted 二维码登录。其他需认证命令在 session 过期时会自动重试一次。
NoCookieError: No 'a1' cookie found — 请先在任意浏览器打开 https://www.xiaohongshu.com/ 并登录，然后执行 xhs loginNeedVerifyError — 触发了验证码，请到浏览器中完成验证后重试IpBlockedError — IP 被限制，尝试切换网络（手机热点或 VPN）SessionExpiredError — Cookie 过期，执行 xhs login 刷新xiaohongshu-cli 自带 SKILL.md，让 AI Agent 能自动学习并使用本工具。
npx skills add jackwener/xiaohongshu-cli| 参数 | 说明 |
|---|---|
-g |
全局安装（用户级别，跨项目共享） |
-a claude-code |
指定目标 Agent |
-y |
非交互模式 |
mkdir -p .agents/skills
git clone [email protected]:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。
Apache-2.0
No open issues yet, or sync has not completed.