xhs-cli

XHS CLI Skill

Interact with Xiaohongshu in the terminal via xiaohongshu-cli .

Prerequisites

# 检查是否已安装并登录
xhs status

If not installed:

uv tool install xiaohongshu-cli
# 升级到最新版本
uv tool upgrade xiaohongshu-cli

xhs login           # 自动提取浏览器 Cookie
xhs login --qrcode  # 扫码登录
xhs whoami          # 确认登录状态

Core Commands

Auth

xhs login                    # 从浏览器自动提取 Cookie
xhs login --qrcode           # 扫码登录（终端显示二维码）
xhs status                   # 检查登录状态
xhs whoami                   # 查看当前用户详细资料
xhs whoami --json            # 结构化 JSON 输出
xhs logout                   # 清除保存的 Cookie

Search

xhs search "关键词"                    # 搜索笔记
xhs search "旅行" --sort popular       # 排序：general, popular, latest
xhs search "穿搭" --type video         # 类型：all, video, image
xhs search "AI" --page 2              # 翻页
xhs search-user "用户名"               # 搜索用户
xhs topics "美食"                      # 搜索话题/标签

Reading

# 短索引（在 search/feed/hot/user-posts 之后使用）
xhs read 1                             # 阅读上次列表的第 1 条笔记
xhs comments 1                         # 查看上次列表的第 1 条笔记评论

# 完整命令
xhs read <note_id>                     # 阅读笔记（仅 API）
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"  # 通过 URL 阅读

xhs comments <url>                     # 查看评论（URL 含 xsec_token）
xhs comments <url> --all               # 获取全部评论（自动翻页）
xhs comments <url> --all --json        # 全部评论，JSON 格式
xhs comments <note_id> --xsec-token T  # 显式指定 token

xhs sub-comments <note_id> <cmt_id>   # 查看评论的回复

xhs user <user_id>                     # 用户主页
xhs user-posts <user_id>              # 用户发布的笔记
xhs user-posts <user_id> --cursor X   # 用 cursor 翻页

Feed & Discovery

xhs feed                              # 推荐 Feed
xhs hot                               # 热门笔记（默认：food）
xhs hot -c fashion                    # 分类：fashion, food, cosmetics,
                                      #       movie, career, love, home,
                                      #       gaming, travel, fitness

Social

xhs favorites                          # 我的收藏夹
xhs favorites <user_id>                # 其他用户的收藏
xhs likes                              # 我的点赞
xhs likes <user_id>                    # 其他用户的点赞
xhs follow <user_id>                   # 关注用户
xhs unfollow <user_id>                 # 取消关注

Interactions

# 短索引形式（在列表命令之后使用）
xhs like 1                             # 给第 1 条笔记点赞
xhs favorite 1                         # 收藏第 1 条笔记
xhs comment 1 -c "好赞！"              # 评论第 1 条笔记
xhs reply 1 --comment-id X -c "回复"   # 回复第 1 条笔记的评论

# 完整形式
xhs like <note_id>                     # 点赞
xhs like <note_id> --undo             # 取消点赞
xhs favorite <note_id>                 # 收藏
xhs unfavorite <note_id>               # 取消收藏
xhs comment <note_id> -c "好赞！"     # 发评论
xhs reply <note_id> --comment-id X -c "回复"  # 回复评论
xhs delete-comment <note_id> <cmt_id> # 删除自己的评论

Creator

xhs my-notes                           # 我的笔记列表
xhs my-notes --page 1                 # 翻页
xhs post --title "标题" --body "正文" --images img.jpg  # 发布图文笔记
xhs delete <note_id>                   # 删除笔记
xhs delete <note_id> -y               # 跳过确认

Notifications

xhs unread                             # 未读数（点赞、@、新关注）
xhs notifications                      # 评论和 @ 通知
xhs notifications --type likes        # 赞和收藏通知
xhs notifications --type connections   # 新增关注通知

Structured Output

All commands support structured output:

xhs <command> --yaml    # YAML 格式（推荐，token 效率高）
xhs <command> --json    # JSON 格式

In non-TTY environments (piped/scripted calls), YAML is output by default.

Unified output envelope format:

ok: true
schema_version: "1"
data: { ... }
error: null

Environment variables control the global format:

OUTPUT=yaml xhs search "美食"   # 强制 YAML
OUTPUT=json xhs whoami          # 强制 JSON

Short-Index Navigation

After executing list commands (search/feed/hot/user-posts/favorites/my-notes), the results are cached in ~/.xiaohongshu-cli/index_cache.json。

Commands that support short indexes:read, comments, like, favorite, unfavorite, comment, reply

xhs search "美食"      # 搜索后缓存结果
xhs read 1            # 阅读第 1 条
xhs comments 1        # 查看第 1 条评论
xhs like 1            # 点赞第 1 条

Error Handling

Error	Solution
`NoCookieError`	After logging in at xiaohongshu.com in a browser, execute `xhs login`
`NeedVerifyError`	Complete the captcha in the browser and retry
`IpBlockedError`	Switch networks (hotspot/VPN)
`SessionExpiredError`	Execute `xhs login` to refresh the Cookie
Slow requests	Normal behavior; built-in Gaussian random delay to avoid risk control

Best Practices

Prefer short indexes: first xhs search, then xhs read 1 operations, smooth and natural
Structured output for automation: add --yaml in scripts for easy parsing
Upgrade regularly：uv tool upgrade xiaohongshu-clito avoid errors caused by API changes
Reasonable frequency: add intervals between batch operations to avoid triggering captchas

Examples

# 场景 1：搜索并阅读笔记
xhs search "川菜教程" --sort popular
xhs read 1
xhs comments 1

# 场景 2：查看用户内容
xhs search-user "某博主"
xhs user-posts <user_id> --yaml

# 场景 3：批量获取热门笔记
xhs hot -c travel --yaml

# 场景 4：互动
xhs search "咖啡探店"
xhs like 1
xhs comment 1 -c "看起来很好喝！"

# 场景 5：获取所有评论
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --yaml