gem-hunter
Language: Python
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-cli
Upgrade 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 git@github.com:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync# ─── Auth ───────────────────────────────────────── xhs login # Extract cookies from browser xhs login --qrcode # Browser-assisted QR login, scan in terminal xhs status # Check login status xhs whoami # Detailed profile (fans, likes, etc) xhs whoami --json # Structured JSON envelope xhs logout # Clear saved cookies # ─── Search ─────────────────────────────────────── xhs search "美食" # Search notes xhs search "旅行" --sort popular # Sort: general, popular, latest xhs search "穿搭" --type video # Filter: all, video, image xhs search "AI" --page 2 # Pagination xhs search-user "用户名" # Search users xhs topics "美食" # Search hashtags/topics # ─── Reading ────────────────────────────────────── xhs read 1 # Read the 1st result from the last list command xhs read <note_id> # Read a note (API only) xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" # Read by URL (uses URL token) xhs comments 1 # Read comments for the 1st result from the last list command xhs comments "<url>" # View comments — paste URL to cache/reuse xsec_token xhs comments "<url>" --all # Fetch ALL comments (auto-paginate all pages) xhs comments "<url>" --all --json # All comments as JSON xhs comments <note_id> --xsec-token T # Use note_id + explicit xsec_token xhs comments <note_id> # Reuse cached token if available xhs sub-comments <note_id> <cmt_id> # View replies to a comment xhs user <user_id> # User profile xhs user-posts <user_id> # User's published notes xhs user-posts <user_id> --cursor X # Paginate with cursor # ─── Feed & Discovery ──────────────────────────── xhs feed # Recommendation feed xhs hot # Hot notes (default: food) xhs hot -c fashion # Categories: fashion, food, cosmetics, # movie, career, love, home, gaming, # travel, fitness # Short index works after list commands such as search/feed/hot/user-posts/favorites/my-notes xhs search "黑丝" xhs read 1 xhs comments 1 xhs like 1 xhs favorite 1 # ─── Social ─────────────────────────────────────── xhs favorites # My bookmarked notes (current user) xhs favorites <user_id> # Other user's bookmarked notes xhs likes # My liked notes (current user) xhs likes <user_id> # Other user's liked notes xhs follow <user_id> # Follow a user xhs unfollow <user_id> # Unfollow a user # ─── Interactions ───────────────────────────────── xhs like 1 # Like the 1st result from the latest note listing xhs like <note_id> # Like a note xhs like <note_id> --undo # Unlike xhs favorite 1 # Favorite the 1st result from the latest note listing xhs favorite <note_id> # Favorite (bookmark) xhs unfavorite 1 # Unfavorite the 1st result from the latest note listing xhs unfavorite <note_id> # Unfavorite xhs comment 1 -c "好赞！" # Comment on the 1st result from the latest note listing xhs comment <note_id> -c "好赞！" # Post comment xhs reply 1 --comment-id X -c "回复" # Reply on the 1st result from the latest note listing xhs reply <note_id> --comment-id X -c "回复" # Reply to comment xhs delete-comment <note_id> <cmt_id> # Delete own comment # ─── Creator ───────────────────────────────────── xhs my-notes # List own notes (v2 creator endpoint) xhs my-notes --page 1 # Next page xhs post --title "标题" --body "正文" --images img.jpg # Post note xhs delete <note_id> # Delete note xhs delete <note_id> -y # Skip confirmation # ─── Notifications ──────────────────────────────── xhs unread # Unread counts (likes, mentions, follows) xhs notifications # 评论和@ notifications xhs notifications --type likes # 赞和收藏 notifications xhs notifications --type connections # 新增关注 notifications
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 git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli
⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
xhs_cli/
├── __init__.py
├── cli.py # Click entry point & command registration
├── client.py # XHS API client (signing, retry, rate-limit, anti-detection)
├── cookies.py # Cookie extraction, TTL management, auto-refresh, token cache
├── signing.py # Main API x-s / x-s-common signature generation
├── creator_signing.py # Creator API AES-128-CBC signature
├── constants.py # URLs, User-Agent, Chrome version, SDK config
├── exceptions.py # Structured exception hierarchy (6 error types)
├── qr_login.py # QR code login (browser-assisted terminal QR + HTTP fallback)
├── formatter.py # Output formatting, schema envelope, Rich rendering
└── commands/
├── _common.py # Shared CLI helpers (structured_output_options, etc.)
├── auth.py # login/logout/status/whoami
├── reading.py # search/read/comments/user/feed/hot/topics/search-user
├── interactions.py # like/favorite/comment/reply/delete-comment
├── social.py # follow/unfollow/favorites
├── creator.py # post/my-notes/delete
└── notifications.py # unread/notifications
# 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 git@github.com:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync# 认证 xhs login # 从浏览器提取 Cookie xhs login --qrcode # browser-assisted 二维码扫码登录（终端显示二维码） xhs status # 检查登录状态 xhs whoami # 查看用户资料 xhs logout # 清除缓存的 Cookie # 搜索 xhs search "美食" # 搜索笔记 xhs search "旅行" --sort popular # 排序：general, popular, latest xhs search-user "用户名" # 搜索用户 xhs topics "美食" # 搜索话题 # 阅读 xhs read 1 # 阅读最近一次列表里的第 1 条笔记 xhs read <note_id> # 阅读笔记（仅走 API） xhs read "https://...?xsec_token=..." # 粘贴网页 URL 直接阅读（使用 URL token） xhs comments 1 # 查看最近一次列表里的第 1 条笔记评论 xhs comments "<url>" # 查看评论 — 粘贴 URL 以缓存/复用 xsec_token xhs comments "<url>" --all # 获取全部评论（自动翻页） xhs comments "<url>" --all --json # 全部评论，JSON 格式 xhs comments <note_id> --xsec-token T # 用 note_id + 显式 xsec_token xhs comments <note_id> # 如果之前访问过 URL，会复用缓存 token xhs sub-comments <note_id> <cmt_id> # 查看评论的回复 xhs user <user_id> # 用户主页 xhs user-posts <user_id> # 用户发布的笔记 # 发现 xhs feed # 推荐 Feed xhs hot -c food # 热门笔记（按分类） xhs hot -c travel # 分类: fashion, food, cosmetics, movie, career, # love, home, gaming, travel, fitness # 社交 xhs favorites # 我的收藏（自动识别当前用户） xhs favorites <user_id> # 其他用户的收藏 xhs likes # 我的点赞（自动识别当前用户） xhs likes <user_id> # 其他用户的点赞 xhs follow <user_id> # 关注 xhs unfollow <user_id> # 取消关注 # 互动 xhs like 1 # 给最近一次列表里的第 1 条笔记点赞 xhs like <note_id> # 点赞 xhs like <note_id> --undo # 取消点赞 xhs favorite 1 # 收藏最近一次列表里的第 1 条笔记 xhs favorite <note_id> # 收藏 xhs unfavorite 1 # 取消收藏最近一次列表里的第 1 条笔记 xhs unfavorite <note_id> # 取消收藏 xhs comment 1 -c "好棒！" # 给最近一次列表里的第 1 条笔记发评论 xhs comment <note_id> -c "好棒！" # 发评论 xhs reply 1 --comment-id X -c "谢谢" # 给最近一次列表里的第 1 条笔记回复评论 xhs reply <note_id> --comment-id X -c "谢谢" # 回复评论 xhs delete-comment <note_id> <cmt_id> # 删除自己的评论 # 创作者 xhs my-notes # 我的笔记列表 xhs post --title "标题" --body "正文" --images img.jpg # 发布笔记 xhs delete <note_id> # 删除笔记 xhs delete <note_id> -y # 跳过确认 # 通知 xhs unread # 未读数 xhs notifications # 评论和 @ 通知 xhs notifications --type likes # 赞和收藏通知 xhs notifications --type connections # 新增关注通知
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 git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli
⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。
Apache-2.0