小红书CLI工具 - 命令行管理小红书笔记、评论、用户，支持搜索、互动、自动化

xiaohongshu-cli by jackwener/xiaohongshu-cli

289 周安装量

1,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jackwener/xiaohongshu-cli --skill xiaohongshu-cli

社交网络自动化命令行工具

🇨🇳中文介绍

xiaohongshu-cli — 小红书 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 已配置。

步骤 0：检查是否已认证

xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

如果输出 AUTH_OK，则跳转到命令参考。如果输出 AUTH_NEEDED，则继续步骤 1。当浏览器 cookie 提取不可用但可以启动浏览器时，优先使用。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 1：引导用户进行认证

确保用户已在任何受 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

步骤 2：处理常见认证问题

症状	代理操作
`NoCookieError: No 'a1' cookie found`	引导用户在浏览器中登录 xiaohongshu.com
`NeedVerifyError: Captcha required`	要求用户打开浏览器，完成验证码，然后重试
`IpBlockedError: IP blocked`	建议切换网络（热点/VPN）
`SessionExpiredError`	运行 `xhs login` 以刷新 cookies

所有机器可读输出都使用 SCHEMA.md 中记录的封装格式。有效载荷位于 .data 下。

非 TTY 标准输出 → 自动 YAML
--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 — 操作不可用

无视频下载 — 无法下载笔记图片/视频
无私信 — 无法访问私人消息
无直播 — 不支持直播功能
无关注者/粉丝列表 — 小红书网页 API 未公开这些端点
单账户 — 一次只能使用一组 cookies
速率限制 — 请求间内置高斯抖动延迟（约 1-1.5 秒）；激进使用可能触发验证码或 IP 封禁

给代理的反检测说明

不要并行化请求 — 内置的速率限制延迟是为了账户安全
验证码恢复：如果发生 NeedVerifyError，客户端会自动冷却并增加延迟（5s→10s→20s→30s）。要求用户在浏览器中完成验证码后再重试
批量操作：当进行批量工作（例如，读取许多笔记）时，在 CLI 调用之间添加 time.sleep()
会话稳定性：会话中的所有请求共享一致的浏览器指纹。重启 CLI 会创建新的指纹会话

不要要求用户在聊天记录中分享原始 cookie 值。
优先使用本地浏览器 cookie 提取，而不是手动复制/粘贴密钥。
如果认证失败，要求用户通过 xhs login 重新登录。
代理应将 cookie 值视为秘密（不要不必要地回显到标准输出）。
内置的速率限制延迟保护账户；不要绕过它。

🇺🇸English

xiaohongshu-cli — Xiaohongshu CLI Tool

Binary: xhs Credentials: browser cookies (auto-extracted) or browser-assisted QR login (--qrcode)

Setup

# 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

Authentication

IMPORTANT FOR AGENTS : Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.

Step 0: Check if already authenticated

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.

Step 1: Guide user to authenticate

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

Step 2: Handle common auth issues

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

Agent Defaults

All machine-readable output uses the envelope documented in SCHEMA.md. Payloads live under .data.

Non-TTY stdout → auto YAML
--json / --yaml → explicit format
OUTPUT=json env → global override
OUTPUT=rich env → force human output

Command Reference

Reading

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	/

Interactions (Write)

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`

Social

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`

Creator

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`

Account

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

Agent Workflow Examples

Search → Read → Like pipeline

NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"

Browse trending food notes

xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'

Get user info then follow

xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123

Check notifications

xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'

Analyze all comments on a note

# 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'

Daily reading workflow

# 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

QR code login

# 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

URL to insights pipeline

# 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

Hot Categories

Available for xhs hot -c <category>: fashion, food, cosmetics, movie, career, love, home, gaming, travel, fitness

Error Codes

Structured error codes returned in the error.code field:

not_authenticated — cookies expired or missing
verification_required — captcha/verification needed
ip_blocked — IP rate limited
signature_error — request signing failed
api_error — upstream API error
unsupported_operation — operation not available

Limitations

No video download — cannot download note images/videos
No DMs — cannot access private messages
No live streaming — live features not supported
No following/followers list — XHS web API doesn't expose these endpoints
Single account — one set of cookies at a time
Rate limited — built-in Gaussian jitter delay (~1-1.5s) between requests; aggressive usage may trigger captchas or IP blocks

Anti-Detection Notes for Agents

Do NOT parallelize requests — the built-in rate-limit delay exists for account safety
Captcha recovery : if NeedVerifyError occurs, the client auto-cools-down with increasing delays (5s→10s→20s→30s). Ask the user to complete captcha in browser before retrying
Batch operations : when doing bulk work (e.g., reading many notes), add time.sleep() between CLI calls
Session stability : all requests in a session share a consistent browser fingerprint. Restarting the CLI creates a new fingerprint session

Safety Notes

Do not ask users to share raw cookie values in chat logs.
Prefer local browser cookie extraction over manual secret copy/paste.
If auth fails, ask the user to re-login via xhs login.
Agent should treat cookie values as secrets (do not echo to stdout unnecessarily).
Built-in rate-limit delay protects accounts; do not bypass it.

Weekly Installs

289

Repository

jackwener/xiaoh…gshu-cli

GitHub Stars

1.4K

First Seen

13 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode277

codex277

gemini-cli275

kimi-cli275

github-copilot275

amp275

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

27,400 周安装

xhs comments "https://...?xsec_token=..."