{"id":47829595,"url":"https://github.com/jackwener/xhs-cli","last_synced_at":"2026-04-03T20:08:06.347Z","repository":{"id":342002446,"uuid":"1172353905","full_name":"jackwener/xhs-cli","owner":"jackwener","description":"小红书命令行工具 — 搜索、阅读、点赞、收藏、评论，全在终端完成 | Xiaohongshu CLI","archived":false,"fork":false,"pushed_at":"2026-03-13T07:31:40.000Z","size":407,"stargazers_count":349,"open_issues_count":4,"forks_count":30,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-13T15:55:48.074Z","etag":null,"topics":["cli","python","redbook","xhs","xiaohongshu"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackwener.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T08:01:48.000Z","updated_at":"2026-03-13T13:49:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jackwener/xhs-cli","commit_stats":null,"previous_names":["jackwener/xhs-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jackwener/xhs-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackwener%2Fxhs-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackwener%2Fxhs-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackwener%2Fxhs-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackwener%2Fxhs-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackwener","download_url":"https://codeload.github.com/jackwener/xhs-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackwener%2Fxhs-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31374127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","python","redbook","xhs","xiaohongshu"],"created_at":"2026-04-03T20:08:05.779Z","updated_at":"2026-04-03T20:08:06.310Z","avatar_url":"https://github.com/jackwener.png","language":"Python","readme":"# xhs-cli\n\n[xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) 这是逆向 API 出来的版本。\n速度更加快更加稳定。但是风控上应该不如当前这个直接用浏览器操作真实。\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 推荐项目\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论、删除笔记\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或 browser-assisted 扫码登录（终端二维码渲染）\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n\u003e 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e从源码安装（开发用）\u003c/summary\u003e\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n\u003c/details\u003e\n\n## 本地一键冒烟测试\n\n在本地已登录（有 `~/.xhs-cli/cookies.json`）的情况下，直接运行：\n\n```bash\n./scripts/smoke_local.sh\n```\n\n可选地传递 pytest 参数（例如只跑某个用例）：\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\n默认只跑无副作用命令（`integration and not live_mutation`）。如需额外验证\n`like/favorite/comment/post/delete`，显式开启：\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\n可选环境变量：\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 强制使用二维码登录（用于排查登录问题）\nxhs login --qrcode\n\n# 手动提供 cookie 字符串（至少包含 a1 和 web_session）\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查已保存的登录状态（不启动浏览器，不读取浏览器 cookie）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read \u003cnote_id\u003e\n\n# 包含评论\nxhs read \u003cnote_id\u003e --comments\n\n# 手动指定 xsec_token\nxhs read \u003cnote_id\u003e --xsec-token \u003ctoken\u003e\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user \u003cuser_id\u003e\n\n# 列出用户笔记\nxhs user-posts \u003cuser_id\u003e\n\n# 粉丝 / 关注\nxhs followers \u003cuser_id\u003e\nxhs following \u003cuser_id\u003e\n```\n\n### 推荐 \u0026 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like \u003cnote_id\u003e\nxhs like \u003cnote_id\u003e --undo\n\n# 收藏 / 取消\nxhs favorite \u003cnote_id\u003e\nxhs favorite \u003cnote_id\u003e --undo\n\n# 评论\nxhs comment \u003cnote_id\u003e \"好棒！\"\n\n# 删除自己的笔记\nxhs delete \u003cnote_id\u003e\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\nxhs post \"标题\" --image photo1.jpg --content \"正文内容\" --json\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`；未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie。`xhs login --qrcode` 使用 browser-assisted 扫码登录，并在终端渲染二维码（`▀ ▄ █`）。\n2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话，并做 feed/search 可用性探活；探活失败会提示重新登录。\n3. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### [Skills CLI](https://github.com/vercel-labs/skills)（推荐）\n\n```bash\nnpx skills add jackwener/xhs-cli\n```\n\n| 参数 | 说明 |\n| --- | --- |\n| `-g` | 全局安装（用户级别，跨项目共享） |\n| `-a claude-code` | 指定目标 Agent |\n| `-y` | 非交互模式 |\n\n### 手动安装\n\n```bash\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### ~~OpenClaw / ClawHub~~（已过时）\n\n\u003e ⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- `xhs status` 只检查本地已保存 cookie，不会触发浏览器 cookie 提取。\n- `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。\n- 登录后会自动做可用性探活；若会话仍为 guest/风控受限，会提示重新登录。\n- `xhs post` 可能要求额外登录创作平台（`https://creator.xiaohongshu.com`）。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackwener%2Fxhs-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackwener%2Fxhs-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackwener%2Fxhs-cli/lists"}