xiaohongshu-cli by jackwener/xiaohongshu-cli
npx skills add https://github.com/jackwener/xiaohongshu-cli --skill xiaohongshu-cli二进制文件: xhs 凭证: 浏览器 cookies(自动提取)或浏览器辅助二维码登录(--qrcode)
# 安装(需要 Python 3.10+)
uv tool install xiaohongshu-cli
# 或者: pipx install xiaohongshu-cli
# 升级到最新版本(推荐以避免 API 错误)
uv tool upgrade xiaohongshu-cli
# 或者: pipx upgrade xiaohongshu-cli
对代理的重要提示:在执行任何 xhs 命令之前,请先检查凭证是否存在。不要假设 cookies 已配置。
xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
如果输出 AUTH_OK,则跳转到命令参考。如果输出 AUTH_NEEDED,则继续步骤 1。当浏览器 cookie 提取不可用但可以启动浏览器时,优先使用 。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
--qrcode确保用户已在任何受 browser_cookie3 支持的浏览器中登录 xiaohongshu.com。支持的浏览器:Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Opera GX、Vivaldi、LibreWolf、Lynx、w3m。然后:
xhs login # 自动检测具有有效 cookies 的浏览器
xhs login --cookie-source arc # 明确指定浏览器
xhs login --qrcode # 浏览器辅助二维码登录,终端输出二维码
使用以下命令验证:
xhs status
xhs whoami
| 症状 | 代理操作 |
|---|---|
NoCookieError: No 'a1' cookie found | 引导用户在浏览器中登录 xiaohongshu.com |
NeedVerifyError: Captcha required | 要求用户打开浏览器,完成验证码,然后重试 |
IpBlockedError: IP blocked | 建议切换网络(热点/VPN) |
SessionExpiredError | 运行 xhs login 以刷新 cookies |
所有机器可读输出都使用 SCHEMA.md 中记录的封装格式。有效载荷位于 .data 下。
--json / --yaml → 显式格式OUTPUT=json 环境变量 → 全局覆盖OUTPUT=rich 环境变量 → 强制人类可读输出| 命令 | 描述 | 示例 |
|---|---|---|
xhs search <keyword> | 搜索笔记 | xhs search "美食" --sort popular --type video |
xhs read <id_or_url_or_index> | 通过 ID、URL 或短索引读取笔记 | xhs read 1 / xhs read "https://...?xsec_token=xxx" |
xhs comments <id_or_url_or_index> | 通过 ID、URL 或短索引获取评论 | xhs comments 1 / xhs comments "https://...?xsec_token=..." |
xhs comments <id_or_url> --all | 获取所有评论(自动分页) | xhs comments "<url>" --all --json |
xhs sub-comments <note_id> <comment_id> | 获取评论的回复 | xhs sub-comments abc 123 |
xhs user <user_id> | 查看用户资料 | xhs user 5f2e123 |
xhs user-posts <user_id> | 列出用户的笔记 | xhs user-posts 5f2e123 --cursor "" |
xhs feed | 浏览推荐流 | xhs feed --yaml |
xhs hot | 浏览热门笔记 | xhs hot -c food |
xhs topics <keyword> | 搜索话题/标签 | xhs topics "旅行" |
xhs search-user <keyword> | 搜索用户 | xhs search-user "摄影" |
xhs my-notes | 列出自己发布的笔记 | xhs my-notes --page 0 |
xhs notifications | 查看通知 | xhs notifications --type likes |
xhs unread | 显示未读计数 | xhs unread --json |
| 命令 | 描述 | 示例 |
|---|---|---|
xhs like <id_or_url_or_index> | 点赞笔记 | xhs like 1 / xhs like abc123 |
xhs like <id_or_url_or_index> --undo | 取消点赞笔记 | xhs like 1 --undo |
xhs favorite <id_or_url_or_index> | 收藏笔记 | xhs favorite 1 |
xhs unfavorite <id_or_url_or_index> | 移除收藏 | xhs unfavorite 1 |
xhs comment <id_or_url_or_index> -c "text" | 发布评论 | xhs comment 1 -c "好看!" |
xhs reply <id_or_url_or_index> --comment-id ID -c "text" | 回复评论 | xhs reply 1 --comment-id 456 -c "谢谢" |
xhs delete-comment <note_id> <comment_id> | 删除自己的评论 | xhs delete-comment abc 123 -y |
| 命令 | 描述 | 示例 |
|---|---|---|
xhs follow <user_id> | 关注用户 | xhs follow 5f2e123 |
xhs unfollow <user_id> | 取消关注用户 | xhs unfollow 5f2e123 |
xhs favorites [user_id] | 列出收藏的笔记(默认为自己) | xhs favorites --json |
| 命令 | 描述 | 示例 |
|---|---|---|
xhs post --title "..." --body "..." --images img.png | 发布笔记 | xhs post --title "Test" --body "Hello" |
xhs delete <id_or_url> | 删除自己的笔记 | xhs delete abc123 -y |
| 命令 | 描述 |
|---|---|
xhs login | 从浏览器提取 cookies(自动检测) |
xhs login --qrcode | 浏览器辅助二维码登录 — 终端输出二维码,浏览器完成登录 |
xhs status | 检查认证状态 |
xhs logout | 清除缓存的 cookies |
xhs whoami | 显示当前用户资料 |
NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"
xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'
xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123
xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'
# 获取所有评论并分析主题
xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
# 统计问题数量
xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'
# 浏览推荐流
xhs feed --yaml
# 交互式短索引工作流
xhs search "旅行"
xhs read 1
xhs comments 1
xhs like 1
xhs favorite 1
xhs comment 1 -c "收藏了"
# 按类别浏览热门
xhs hot -c food --yaml
xhs hot -c travel --yaml
# 当浏览器 cookie 提取不可用时
xhs login --qrcode
# → 启动浏览器辅助登录流程
# → 使用 Unicode 半块字符在终端渲染二维码
# → 使用小红书应用扫描 → 确认 → 导出 cookies
# 用户粘贴 URL → 阅读 + 所有评论
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json
可用于 xhs hot -c <category>:fashion, food, cosmetics, movie, career, love, home, gaming, travel, fitness
在 error.code 字段中返回的结构化错误代码:
not_authenticated — cookies 过期或缺失verification_required — 需要验证码/验证ip_blocked — IP 被限速signature_error — 请求签名失败api_error — 上游 API 错误unsupported_operation — 操作不可用NeedVerifyError,客户端会自动冷却并增加延迟(5s→10s→20s→30s)。要求用户在浏览器中完成验证码后再重试time.sleep()xhs login 重新登录。每周安装数
289
仓库
GitHub 星标
1.4K
首次出现
13 天前
安全审计
安装于
opencode277
codex277
gemini-cli275
kimi-cli275
github-copilot275
amp275
Binary: xhs Credentials: browser cookies (auto-extracted) or browser-assisted QR login (--qrcode)
# Install (requires Python 3.10+)
uv tool install xiaohongshu-cli
# Or: pipx install xiaohongshu-cli
# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade xiaohongshu-cli
# Or: pipx upgrade xiaohongshu-cli
IMPORTANT FOR AGENTS : Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.
xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
If AUTH_OK, skip to Command Reference. If AUTH_NEEDED, proceed to Step 1. Prefer --qrcode when browser cookie extraction is unavailable but launching a browser is acceptable.
Ensure user is logged into xiaohongshu.com in any browser supported by browser_cookie3. Supported browsers: Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Opera GX, Vivaldi, LibreWolf, Lynx, w3m. Then:
xhs login # auto-detect browser with valid cookies
xhs login --cookie-source arc # specify browser explicitly
xhs login --qrcode # browser-assisted QR login with terminal QR output
Verify with:
xhs status
xhs whoami
| Symptom | Agent action |
|---|---|
NoCookieError: No 'a1' cookie found | Guide user to login to xiaohongshu.com in browser |
NeedVerifyError: Captcha required | Ask user to open browser, complete captcha, then retry |
IpBlockedError: IP blocked | Suggest switching network (hotspot/VPN) |
SessionExpiredError | Run xhs login to refresh cookies |
All machine-readable output uses the envelope documented in SCHEMA.md. Payloads live under .data.
--json / --yaml → explicit formatOUTPUT=json env → global overrideOUTPUT=rich env → force human output| Command | Description | Example |
|---|---|---|
xhs search <keyword> | Search notes | xhs search "美食" --sort popular --type video |
xhs read <id_or_url_or_index> | Read a note by ID, URL, or short index | xhs read 1 / xhs read "https://...?xsec_token=xxx" |
xhs comments <id_or_url_or_index> | Get comments by ID, URL, or short index | / |
| Command | Description | Example |
|---|---|---|
xhs like <id_or_url_or_index> | Like a note | xhs like 1 / xhs like abc123 |
xhs like <id_or_url_or_index> --undo | Unlike a note | xhs like 1 --undo |
xhs favorite <id_or_url_or_index> | Bookmark a note | xhs favorite 1 |
| Command | Description | Example |
|---|---|---|
xhs follow <user_id> | Follow a user | xhs follow 5f2e123 |
xhs unfollow <user_id> | Unfollow a user | xhs unfollow 5f2e123 |
xhs favorites [user_id] | List bookmarked notes (defaults to self) | xhs favorites --json |
| Command | Description | Example |
|---|---|---|
xhs post --title "..." --body "..." --images img.png | Publish a note | xhs post --title "Test" --body "Hello" |
xhs delete <id_or_url> | Delete own note | xhs delete abc123 -y |
| Command | Description |
|---|---|
xhs login | Extract cookies from browser (auto-detect) |
xhs login --qrcode | Browser-assisted QR login — terminal QR output, browser completes login |
xhs status | Check authentication status |
xhs logout | Clear cached cookies |
xhs whoami | Show current user profile |
NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"
xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'
xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123
xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'
# Fetch ALL comments and analyze themes
xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
# Count questions
xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'
# Browse recommendation feed
xhs feed --yaml
# Interactive short-index workflow
xhs search "旅行"
xhs read 1
xhs comments 1
xhs like 1
xhs favorite 1
xhs comment 1 -c "收藏了"
# Browse trending by category
xhs hot -c food --yaml
xhs hot -c travel --yaml
# When browser cookie extraction is not available
xhs login --qrcode
# → Launches a browser-assisted login flow
# → Renders QR in terminal using Unicode half-blocks
# → Scan with Xiaohongshu app → confirm → export cookies
# User pastes a URL → read + all comments
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json
Available for xhs hot -c <category>: fashion, food, cosmetics, movie, career, love, home, gaming, travel, fitness
Structured error codes returned in the error.code field:
not_authenticated — cookies expired or missingverification_required — captcha/verification neededip_blocked — IP rate limitedsignature_error — request signing failedapi_error — upstream API errorunsupported_operation — operation not availableNeedVerifyError occurs, the client auto-cools-down with increasing delays (5s→10s→20s→30s). Ask the user to complete captcha in browser before retryingtime.sleep() between CLI callsxhs login.Weekly Installs
289
Repository
GitHub Stars
1.4K
First Seen
13 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode277
codex277
gemini-cli275
kimi-cli275
github-copilot275
amp275
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
27,400 周安装
xhs comments 1xhs comments "https://...?xsec_token=..."xhs comments <id_or_url> --all | Get ALL comments (auto-paginate) | xhs comments "<url>" --all --json |
xhs sub-comments <note_id> <comment_id> | Get replies to comment | xhs sub-comments abc 123 |
xhs user <user_id> | View user profile | xhs user 5f2e123 |
xhs user-posts <user_id> | List user's notes | xhs user-posts 5f2e123 --cursor "" |
xhs feed | Browse recommendation feed | xhs feed --yaml |
xhs hot | Browse trending notes | xhs hot -c food |
xhs topics <keyword> | Search topics/hashtags | xhs topics "旅行" |
xhs search-user <keyword> | Search users | xhs search-user "摄影" |
xhs my-notes | List own published notes | xhs my-notes --page 0 |
xhs notifications | View notifications | xhs notifications --type likes |
xhs unread | Show unread counts | xhs unread --json |
xhs unfavorite <id_or_url_or_index> | Remove bookmark | xhs unfavorite 1 |
xhs comment <id_or_url_or_index> -c "text" | Post a comment | xhs comment 1 -c "好看!" |
xhs reply <id_or_url_or_index> --comment-id ID -c "text" | Reply to comment | xhs reply 1 --comment-id 456 -c "谢谢" |
xhs delete-comment <note_id> <comment_id> | Delete own comment | xhs delete-comment abc 123 -y |