Skip to content
Back to search

xhs-cli

小红书命令行工具 — 搜索、阅读、点赞、收藏、评论,全在终端完成 | Xiaohongshu CLI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jackwener--xhs-cli/badge.svg)](/listings/jackwener--xhs-cli)

HTML

<a href="/listings/jackwener--xhs-cli"><img src="/api/listings/jackwener--xhs-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

需要 Python 3.8+。

# 推荐:使用 uv
uv tool install xhs-cli

# 或使用 pipx
pipx install xhs-cli

<details> <summary>从源码安装(开发用)</summary>

git clone git@github.com:jackwener/xhs-cli.git
cd xhs-cli
uv sync

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 169 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: xhs-cli
  3. description: "Headless-browser-based CLI skill for Xiaohongshu (小红书, RedNote, XHS) to search notes, read posts, browse profiles, like, favorite, comment, and publish from the terminal"
  4. author: jackwener
  5. version: "1.0.0"
  6. tags:
  7. - xhs
  8. - xiaohongshu
  9. - 小红书
  10. - rednote
  11. - social-media
  12. - cli
  13. ---
  14. > [!NOTE]
  15. > An alternative package [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) is available, which uses a reverse-engineered API and runs faster.
  16. > This package (`xhs-cli`) uses a headless browser (camoufox) approach — slower but more resilient against risk-control detection.
  17. > Choose whichever best fits your needs.
  18. # xhs-cli Skill
  19. A CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.
  20. ## Prerequisites
  21. ```bash
  22. # Install (requires Python 3.8+)
  23. uv tool install xhs-cli
  24. # Or: pipx install xhs-cli
  25. ```
  26. ## Authentication
  27. All commands require valid cookies to function.
  28. ```bash
  29. xhs status # Check saved login session (no browser extraction)
  30. xhs login # Auto-extract Chrome cookies
  31. xhs login --cookie "a1=..." # Or provide cookies manually
  32. ```
  33. Authentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.
  34. ## Command Reference
  35. ### Search
  36. ```bash
  37. xhs search "咖啡" # Search notes (rich table output)
  38. xhs search "咖啡" --json # Raw JSON output
  39. ```
  40. ### Read Note
  41. ```bash
  42. # View note (xsec_token auto-resolved from search cache)
  43. xhs read <note_id>
  44. xhs read <note_id> --comments # Include comments
  45. xhs read <note_id> --xsec-token <token> # Manual token
  46. xhs read <note_id> --json
  47. ```
  48. ### User
  49. ```bash
  50. # Look up user profile (by internal user_id, hex format)
  51. xhs user <user_id>
  52. xhs user <user_id> --json
  53. # List user's published notes
  54. xhs user-posts <user_id>
  55. xhs user-posts <user_id> --json
  56. # Followers / Following
  57. xhs followers <user_id>
  58. xhs following <user_id>
  59. ```
  60. ### Discovery
  61. ```bash
  62. xhs feed # Explore page recommended feed
  63. xhs feed --json
  64. xhs topics "旅行" # Search topics/hashtags
  65. xhs topics "旅行" --json
  66. ```
  67. ### Interactions (require login)
  68. ```bash
  69. # Like / Unlike (xsec_token auto-resolved)
  70. xhs like <note_id>
  71. xhs like <note_id> --undo
  72. # Favorite / Unfavorite
  73. xhs favorite <note_id>
  74. xhs favorite <note_id> --undo
  75. # Comment
  76. xhs comment <note_id> "好棒!"
  77. # Delete your own note
  78. xhs delete <note_id>
  79. ```
  80. ### Favorites
  81. ```bash
  82. xhs favorites # List your favorites
  83. xhs favorites --max 10 # Limit count
  84. xhs favorites --json
  85. ```
  86. ### Post
  87. ```bash
  88. xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文"
  89. xhs post "标题" --image photo1.jpg --content "正文" --json
  90. ```
  91. ### Account
  92. ```bash
  93. xhs status # Quick saved-session check
  94. xhs whoami # Full profile info
  95. xhs whoami --json
  96. xhs login # Login
  97. xhs logout # Clear cookies
  98. ```
  99. ## JSON Output
  100. Major query commands support `--json` for machine-readable output:
  101. ```bash
  102. xhs search "咖啡" --json | jq '.[0].id' # First note ID
  103. xhs whoami --json | jq '.userInfo.userId' # Your user ID
  104. xhs favorites --json | jq '.[0].displayTitle' # First favorite title
  105. ```
  106. ## Common Patterns for AI Agents
  107. ```bash
  108. # Get your user ID for further queries
  109. xhs whoami --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))"
  110. # Search and get note IDs (xsec_token auto-cached for later use)
  111. xhs search "topic" --json | python3 -c "import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]"
  112. # Check login before performing actions
  113. xhs status && xhs like <note_id>
  114. # Read a note with comments for summarization
  115. xhs read <note_id> --comments --json
  116. ```
  117. ## Error Handling
  118. - Commands exit with code 0 on success, non-zero on failure
  119. - Error messages are prefixed with ❌
  120. - Login-required commands show clear instruction to run `xhs login`
  121. - `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback
  122. ## Safety Notes
  123. - Do not ask users to share raw cookie values in chat logs.
  124. - Prefer auto-extraction via `xhs login` over manual cookie input.
  125. - If auth fails, ask the user to re-login via `xhs login`.
README.md · README · 275 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # xhs-cli
  2. [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) 这是逆向 API 出来的版本。
  3. 速度更加快更加稳定。但是风控上应该不如当前这个直接用浏览器操作真实。
  4. **中文** | [English](README_EN.md)
  5. [![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)
  6. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  7. 小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。
  8. ## 推荐项目
  9. - [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具
  10. - [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具
  11. ## 功能
  12. - **搜索** — 按关键词搜索笔记,Rich 表格展示
  13. - **阅读** — 查看笔记内容、数据、评论
  14. - **用户资料** — 查看用户信息、笔记、粉丝、关注
  15. - **推荐 Feed** — 获取探索页推荐内容
  16. - **话题** — 搜索话题标签
  17. - **互动** — 点赞/取消、收藏/取消、评论、删除笔记
  18. - **发布** — 发布图文笔记
  19. - **认证** — 自动提取 Chrome cookie,或 browser-assisted 扫码登录(终端二维码渲染)
  20. - **JSON 输出** — 所有数据命令支持 `--json`
  21. - **Token 自动缓存** — `xsec_token` 搜索后自动缓存,后续命令免手动传
  22. ## 命令一览
  23. | 分类 | 命令 | 说明 |
  24. |------|------|------|
  25. | Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |
  26. | Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |
  27. | Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |
  28. | Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |
  29. | Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |
  30. | Post | `post` | 发布图文笔记 |
  31. > 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存,无需手动传递。
  32. ## 特别鸣谢
  33. <p align="center">
  34. <a href="https://www.ipwo.net/">
  35. <img src="assets/ipwo-banner.jpg" alt="IPWO 住宅代理" width="100%" />
  36. </a>
  37. </p>
  38. [<ins>IPWO住宅代理</ins>](https://www.ipwo.net/)覆盖 195+ 个国家和地区,提供动态住宅代理、静态住宅代理及不限量住宅代理。<br>
  39. 适用于开发 CLI 工具、集成 MCP 服务,构建 AI Agent 与自动化工作流,为多地区网络访问和数据采集任务提供灵活的住宅代理选择。<br>
  40. 支持免费测试,9 折折扣码:`0203`
  41. ---
  42. ## 安装
  43. 需要 Python 3.8+。
  44. ```bash
  45. # 推荐:使用 uv
  46. uv tool install xhs-cli
  47. # 或使用 pipx
  48. pipx install xhs-cli
  49. ```
  50. <details>
  51. <summary>从源码安装(开发用)</summary>
  52. ```bash
  53. git clone git@github.com:jackwener/xhs-cli.git
  54. cd xhs-cli
  55. uv sync
  56. ```
  57. </details>
  58. ## 本地一键冒烟测试
  59. 在本地已登录(有 `~/.xhs-cli/cookies.json`)的情况下,直接运行:
  60. ```bash
  61. ./scripts/smoke_local.sh
  62. ```
  63. 可选地传递 pytest 参数(例如只跑某个用例):
  64. ```bash
  65. ./scripts/smoke_local.sh -k whoami
  66. ```
  67. 默认只跑无副作用命令(`integration and not live_mutation`)。如需额外验证
  68. `like/favorite/comment/post/delete`,显式开启:
  69. ```bash
  70. XHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh
  71. ```
  72. 可选环境变量:
  73. ```bash
  74. XHS_SMOKE_COMMENT_TEXT="smoke test comment"
  75. XHS_SMOKE_POST_IMAGES="/abs/a.jpg,/abs/b.jpg"
  76. XHS_SMOKE_POST_TITLE="smoke title"
  77. XHS_SMOKE_POST_CONTENT="smoke content"
  78. ```
  79. ## 使用
  80. ### 登录
  81. ```bash
  82. # 自动从 Chrome 提取 cookie(推荐)
  83. xhs login
  84. # 强制使用二维码登录(用于排查登录问题)
  85. xhs login --qrcode
  86. # 手动提供 cookie 字符串(至少包含 a1 和 web_session)
  87. xhs login --cookie "a1=xxx; web_session=yyy"
  88. # 快速检查已保存的登录状态(不启动浏览器,不读取浏览器 cookie)
  89. xhs status
  90. # 查看个人资料
  91. xhs whoami
  92. xhs whoami --json
  93. # 退出登录
  94. xhs logout
  95. ```
  96. ### 搜索
  97. ```bash
  98. xhs search "咖啡"
  99. xhs search "咖啡" --json
  100. ```
  101. ### 阅读笔记
  102. ```bash
  103. # 查看笔记(xsec_token 从缓存自动解析)
  104. xhs read <note_id>
  105. # 包含评论
  106. xhs read <note_id> --comments
  107. # 手动指定 xsec_token
  108. xhs read <note_id> --xsec-token <token>
  109. ```
  110. ### 用户
  111. ```bash
  112. # 查看用户资料(使用内部 user_id,非小红书号)
  113. xhs user <user_id>
  114. # 列出用户笔记
  115. xhs user-posts <user_id>
  116. # 粉丝 / 关注
  117. xhs followers <user_id>
  118. xhs following <user_id>
  119. ```
  120. ### 推荐 & 话题
  121. ```bash
  122. xhs feed
  123. xhs topics "旅行"
  124. ```
  125. ### 互动
  126. ```bash
  127. # 点赞 / 取消(xsec_token 自动解析)
  128. xhs like <note_id>
  129. xhs like <note_id> --undo
  130. # 收藏 / 取消
  131. xhs favorite <note_id>
  132. xhs favorite <note_id> --undo
  133. # 评论
  134. xhs comment <note_id> "好棒!"
  135. # 删除自己的笔记
  136. xhs delete <note_id>
  137. # 查看收藏列表
  138. xhs favorites
  139. xhs favorites --max 10
  140. ```
  141. ### 发布笔记
  142. ```bash
  143. xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文内容"
  144. xhs post "标题" --image photo1.jpg --content "正文内容" --json
  145. ```
  146. ### 其他
  147. ```bash
  148. xhs --version
  149. xhs -v search "咖啡" # 调试日志
  150. xhs --help
  151. ```
  152. ## 架构
  153. ```
  154. CLI (click) → XhsClient (camoufox 浏览器)
  155. ↓ 导航到真实页面
  156. window.__INITIAL_STATE__ → 提取结构化数据
  157. ```
  158. 使用 [camoufox](https://github.com/daijro/camoufox)(反指纹 Firefox)像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取,与正常浏览完全一致。
  159. ## 工作原理
  160. 1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`;未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie。`xhs login --qrcode` 使用 browser-assisted 扫码登录,并在终端渲染二维码(`▀ ▄ █`)。
  161. 2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话,并做 feed/search 可用性探活;探活失败会提示重新登录。
  162. 3. **浏览** — 使用 camoufox 导航到真实页面,所有流量与正常用户浏览一致。
  163. 4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。
  164. 5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。
  165. 6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。
  166. ## 作为 AI Agent Skill 使用
  167. xhs-cli 自带 [`SKILL.md`](./SKILL.md),让 AI Agent 能自动学习并使用本工具。
  168. ### [Skills CLI](https://github.com/vercel-labs/skills)(推荐)
  169. ```bash
  170. npx skills add jackwener/xhs-cli
  171. ```
  172. | 参数 | 说明 |
  173. | --- | --- |
  174. | `-g` | 全局安装(用户级别,跨项目共享) |
  175. | `-a claude-code` | 指定目标 Agent |
  176. | `-y` | 非交互模式 |
  177. ### 手动安装
  178. ```bash
  179. mkdir -p .agents/skills
  180. git clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli
  181. ```
  182. 添加后,支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。
  183. ### ~~OpenClaw / ClawHub~~(已过时)
  184. > ⚠️ ClawHub 安装方式已过时,不再支持。请使用上方的 Skills CLI 或手动安装。
  185. ## 注意事项
  186. - Cookie 存储在 `~/.xhs-cli/cookies.json`,权限 `0600`。
  187. - `xhs status` 只检查本地已保存 cookie,不会触发浏览器 cookie 提取。
  188. - `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。
  189. - 登录后会自动做可用性探活;若会话仍为 guest/风控受限,会提示重新登录。
  190. - `xhs post` 可能要求额外登录创作平台(`https://creator.xiaohongshu.com`)。
  191. - 使用 headless Firefox,不会弹出浏览器窗口。
  192. - 首次运行需下载 camoufox 浏览器(`python -m camoufox fetch`)。
  193. - 用户资料查询需要内部 user_id(十六进制),不是小红书号。
  194. ## License
  195. Apache License 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.