xhs-cli
小红书命令行工具 — 搜索、阅读、点赞、收藏、评论,全在终端完成 | Xiaohongshu CLI
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/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
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.
- ---
- name: xhs-cli
- 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"
- author: jackwener
- version: "1.0.0"
- tags:
- - xhs
- - xiaohongshu
- - 小红书
- - rednote
- - social-media
- - cli
- ---
- > [!NOTE]
- > An alternative package [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) is available, which uses a reverse-engineered API and runs faster.
- > This package (`xhs-cli`) uses a headless browser (camoufox) approach — slower but more resilient against risk-control detection.
- > Choose whichever best fits your needs.
- # xhs-cli Skill
- 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.
- ## Prerequisites
- ```bash
- # Install (requires Python 3.8+)
- uv tool install xhs-cli
- # Or: pipx install xhs-cli
- ```
- ## Authentication
- All commands require valid cookies to function.
- ```bash
- xhs status # Check saved login session (no browser extraction)
- xhs login # Auto-extract Chrome cookies
- xhs login --cookie "a1=..." # Or provide cookies manually
- ```
- 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.
- ## Command Reference
- ### Search
- ```bash
- xhs search "咖啡" # Search notes (rich table output)
- xhs search "咖啡" --json # Raw JSON output
- ```
- ### Read Note
- ```bash
- # View note (xsec_token auto-resolved from search cache)
- xhs read <note_id>
- xhs read <note_id> --comments # Include comments
- xhs read <note_id> --xsec-token <token> # Manual token
- xhs read <note_id> --json
- ```
- ### User
- ```bash
- # Look up user profile (by internal user_id, hex format)
- xhs user <user_id>
- xhs user <user_id> --json
- # List user's published notes
- xhs user-posts <user_id>
- xhs user-posts <user_id> --json
- # Followers / Following
- xhs followers <user_id>
- xhs following <user_id>
- ```
- ### Discovery
- ```bash
- xhs feed # Explore page recommended feed
- xhs feed --json
- xhs topics "旅行" # Search topics/hashtags
- xhs topics "旅行" --json
- ```
- ### Interactions (require login)
- ```bash
- # Like / Unlike (xsec_token auto-resolved)
- xhs like <note_id>
- xhs like <note_id> --undo
- # Favorite / Unfavorite
- xhs favorite <note_id>
- xhs favorite <note_id> --undo
- # Comment
- xhs comment <note_id> "好棒!"
- # Delete your own note
- xhs delete <note_id>
- ```
- ### Favorites
- ```bash
- xhs favorites # List your favorites
- xhs favorites --max 10 # Limit count
- xhs favorites --json
- ```
- ### Post
- ```bash
- xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文"
- xhs post "标题" --image photo1.jpg --content "正文" --json
- ```
- ### Account
- ```bash
- xhs status # Quick saved-session check
- xhs whoami # Full profile info
- xhs whoami --json
- xhs login # Login
- xhs logout # Clear cookies
- ```
- ## JSON Output
- Major query commands support `--json` for machine-readable output:
- ```bash
- xhs search "咖啡" --json | jq '.[0].id' # First note ID
- xhs whoami --json | jq '.userInfo.userId' # Your user ID
- xhs favorites --json | jq '.[0].displayTitle' # First favorite title
- ```
- ## Common Patterns for AI Agents
- ```bash
- # Get your user ID for further queries
- xhs whoami --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))"
- # Search and get note IDs (xsec_token auto-cached for later use)
- xhs search "topic" --json | python3 -c "import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]"
- # Check login before performing actions
- xhs status && xhs like <note_id>
- # Read a note with comments for summarization
- xhs read <note_id> --comments --json
- ```
- ## Error Handling
- - Commands exit with code 0 on success, non-zero on failure
- - Error messages are prefixed with ❌
- - Login-required commands show clear instruction to run `xhs login`
- - `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback
- ## Safety Notes
- - Do not ask users to share raw cookie values in chat logs.
- - Prefer auto-extraction via `xhs login` over manual cookie input.
- - 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.
- # xhs-cli
- [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) 这是逆向 API 出来的版本。
- 速度更加快更加稳定。但是风控上应该不如当前这个直接用浏览器操作真实。
- **中文** | [English](README_EN.md)
- [](https://pypi.org/project/xhs-cli/)
- [](LICENSE)
- 小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。
- ## 推荐项目
- - [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具
- - [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具
- ## 功能
- - **搜索** — 按关键词搜索笔记,Rich 表格展示
- - **阅读** — 查看笔记内容、数据、评论
- - **用户资料** — 查看用户信息、笔记、粉丝、关注
- - **推荐 Feed** — 获取探索页推荐内容
- - **话题** — 搜索话题标签
- - **互动** — 点赞/取消、收藏/取消、评论、删除笔记
- - **发布** — 发布图文笔记
- - **认证** — 自动提取 Chrome cookie,或 browser-assisted 扫码登录(终端二维码渲染)
- - **JSON 输出** — 所有数据命令支持 `--json`
- - **Token 自动缓存** — `xsec_token` 搜索后自动缓存,后续命令免手动传
- ## 命令一览
- | 分类 | 命令 | 说明 |
- |------|------|------|
- | Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |
- | Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |
- | Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |
- | Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |
- | Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |
- | Post | `post` | 发布图文笔记 |
- > 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存,无需手动传递。
- ## 特别鸣谢
- <p align="center">
- <a href="https://www.ipwo.net/">
- <img src="assets/ipwo-banner.jpg" alt="IPWO 住宅代理" width="100%" />
- </a>
- </p>
- [<ins>IPWO住宅代理</ins>](https://www.ipwo.net/)覆盖 195+ 个国家和地区,提供动态住宅代理、静态住宅代理及不限量住宅代理。<br>
- 适用于开发 CLI 工具、集成 MCP 服务,构建 AI Agent 与自动化工作流,为多地区网络访问和数据采集任务提供灵活的住宅代理选择。<br>
- 支持免费测试,9 折折扣码:`0203`
- ---
- ## 安装
- 需要 Python 3.8+。
- ```bash
- # 推荐:使用 uv
- uv tool install xhs-cli
- # 或使用 pipx
- pipx install xhs-cli
- ```
- <details>
- <summary>从源码安装(开发用)</summary>
- ```bash
- git clone git@github.com:jackwener/xhs-cli.git
- cd xhs-cli
- uv sync
- ```
- </details>
- ## 本地一键冒烟测试
- 在本地已登录(有 `~/.xhs-cli/cookies.json`)的情况下,直接运行:
- ```bash
- ./scripts/smoke_local.sh
- ```
- 可选地传递 pytest 参数(例如只跑某个用例):
- ```bash
- ./scripts/smoke_local.sh -k whoami
- ```
- 默认只跑无副作用命令(`integration and not live_mutation`)。如需额外验证
- `like/favorite/comment/post/delete`,显式开启:
- ```bash
- XHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh
- ```
- 可选环境变量:
- ```bash
- XHS_SMOKE_COMMENT_TEXT="smoke test comment"
- XHS_SMOKE_POST_IMAGES="/abs/a.jpg,/abs/b.jpg"
- XHS_SMOKE_POST_TITLE="smoke title"
- XHS_SMOKE_POST_CONTENT="smoke content"
- ```
- ## 使用
- ### 登录
- ```bash
- # 自动从 Chrome 提取 cookie(推荐)
- xhs login
- # 强制使用二维码登录(用于排查登录问题)
- xhs login --qrcode
- # 手动提供 cookie 字符串(至少包含 a1 和 web_session)
- xhs login --cookie "a1=xxx; web_session=yyy"
- # 快速检查已保存的登录状态(不启动浏览器,不读取浏览器 cookie)
- xhs status
- # 查看个人资料
- xhs whoami
- xhs whoami --json
- # 退出登录
- xhs logout
- ```
- ### 搜索
- ```bash
- xhs search "咖啡"
- xhs search "咖啡" --json
- ```
- ### 阅读笔记
- ```bash
- # 查看笔记(xsec_token 从缓存自动解析)
- xhs read <note_id>
- # 包含评论
- xhs read <note_id> --comments
- # 手动指定 xsec_token
- xhs read <note_id> --xsec-token <token>
- ```
- ### 用户
- ```bash
- # 查看用户资料(使用内部 user_id,非小红书号)
- xhs user <user_id>
- # 列出用户笔记
- xhs user-posts <user_id>
- # 粉丝 / 关注
- xhs followers <user_id>
- xhs following <user_id>
- ```
- ### 推荐 & 话题
- ```bash
- xhs feed
- xhs topics "旅行"
- ```
- ### 互动
- ```bash
- # 点赞 / 取消(xsec_token 自动解析)
- xhs like <note_id>
- xhs like <note_id> --undo
- # 收藏 / 取消
- xhs favorite <note_id>
- xhs favorite <note_id> --undo
- # 评论
- xhs comment <note_id> "好棒!"
- # 删除自己的笔记
- xhs delete <note_id>
- # 查看收藏列表
- xhs favorites
- xhs favorites --max 10
- ```
- ### 发布笔记
- ```bash
- xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文内容"
- xhs post "标题" --image photo1.jpg --content "正文内容" --json
- ```
- ### 其他
- ```bash
- xhs --version
- xhs -v search "咖啡" # 调试日志
- xhs --help
- ```
- ## 架构
- ```
- CLI (click) → XhsClient (camoufox 浏览器)
- ↓ 导航到真实页面
- window.__INITIAL_STATE__ → 提取结构化数据
- ```
- 使用 [camoufox](https://github.com/daijro/camoufox)(反指纹 Firefox)像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取,与正常浏览完全一致。
- ## 工作原理
- 1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`;未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie。`xhs login --qrcode` 使用 browser-assisted 扫码登录,并在终端渲染二维码(`▀ ▄ █`)。
- 2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话,并做 feed/search 可用性探活;探活失败会提示重新登录。
- 3. **浏览** — 使用 camoufox 导航到真实页面,所有流量与正常用户浏览一致。
- 4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。
- 5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。
- 6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。
- ## 作为 AI Agent Skill 使用
- xhs-cli 自带 [`SKILL.md`](./SKILL.md),让 AI Agent 能自动学习并使用本工具。
- ### [Skills CLI](https://github.com/vercel-labs/skills)(推荐)
- ```bash
- npx skills add jackwener/xhs-cli
- ```
- | 参数 | 说明 |
- | --- | --- |
- | `-g` | 全局安装(用户级别,跨项目共享) |
- | `-a claude-code` | 指定目标 Agent |
- | `-y` | 非交互模式 |
- ### 手动安装
- ```bash
- mkdir -p .agents/skills
- git clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli
- ```
- 添加后,支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。
- ### ~~OpenClaw / ClawHub~~(已过时)
- > ⚠️ ClawHub 安装方式已过时,不再支持。请使用上方的 Skills CLI 或手动安装。
- ## 注意事项
- - Cookie 存储在 `~/.xhs-cli/cookies.json`,权限 `0600`。
- - `xhs status` 只检查本地已保存 cookie,不会触发浏览器 cookie 提取。
- - `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。
- - 登录后会自动做可用性探活;若会话仍为 guest/风控受限,会提示重新登录。
- - `xhs post` 可能要求额外登录创作平台(`https://creator.xiaohongshu.com`)。
- - 使用 headless Firefox,不会弹出浏览器窗口。
- - 首次运行需下载 camoufox 浏览器(`python -m camoufox fetch`)。
- - 用户资料查询需要内部 user_id(十六进制),不是小红书号。
- ## License
- Apache License 2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.