xhs-cli 是面向终端的小红书（Xiaohongshu / RED）自动化工具，支持登录、创作者指标采集、已发笔记列表、笔记详情抓取，以及通过标题 + 正文 + 本地图片在创作后台自动填表发帖（需本机 Chrome/Chromium）。
xhs-cli · xiaohongshu-cli · 小红书自动化 · 小红书命令行 · 小红书发帖工具 · 小红书 CLI · 小红书 bot · Xiaohongshu automation · Xiaohongshu CLI · RED note automation · 小红书创作者工具 · xhs automation
xhs-cli（也称 xiaohongshu-cli）是一款基于 Puppeteer 的小红书自动化命令行工具，无需破解 API，通过控制本机浏览器操作小红书创作者后台，实现：
- 📥 登录 —— 浏览器扫码/账密登录，Cookie 持久化
- 📊 创作者指标 —— 一键拉取运营数据摘要
- 📝 笔记管理 —— 已发笔记列表 & 单篇详情
- 🖼️ 自动发帖 —— 填入标题、正文、本地图片，自动操作创作后台
- 👥 多账号隔离 —— 每账号独立浏览器会话，互不干扰
- 🗂️ 草稿 & 审批流 —— 本地草稿管理 + 人工审批后再发布
适合与 JooOS / Agent 编排集成，也可单独作为小红书自动化脚本在本地使用。
- Node.js 20 及以上
- Chrome 或 Chromium（不随包下载；由 Puppeteer 连接本机浏览器）
npm install -g xhs-cli
xhs helpgit clone https://github.com/joohw/xhs-cli.git
cd xhs-cli
npm install
npm run build构建产物入口为 dist/cli/index.js，等价于命令 xhs。
默认数据在 ~/.xhs-cli/.cache/。
- 未配置多账号时：会话与 Cookie 使用
~/.xhs-cli/.cache/browser-data。 - 配置多账号后：每个账号有独立
~/.xhs-cli/.cache/accounts/<name>/browser-data；注册表accounts/registry.json记录currentAccount。未设置默认账号或未带--account时仍会落回browser-data，避免老用户被迁档。
草稿在 drafts/，发布后本地归档记录在 published/（仅记账，不可替代平台侧状态）。
本工具 不会静默向小红书发稿。xhs post 默认只打开创作页并填入内容；是否正式发布由你本人决定。加 --publish 才会在浏览器里尝试自动点击「发布」。
xhs draft publish 同上：只有在人工走通该命令、且草稿已 draft approve 后才会发起浏览器发帖流程；失败后草稿状态仍为 approved。
xhs account add joo-main --display-name Joo --role personal
xhs account add agidaily --display-name agidaily --role media
xhs account add clovapi --display-name clovapi --role product
xhs account use agidaily
xhs account current按账号登录（会话目录互不干扰）：
xhs login --account joo-main
xhs login --account agidaily发帖或拉数据时显式指定账号：
xhs post --account clovapi --title "标题" --content "正文至少十个字小红书校验" --image ./cover.png
xhs metrics --account agidaily
xhs posted --account agidaily --limit 20若已 account use <name>，可省略 --account。
xhs draft create --account agidaily --title "选题标题" \
--content "正文内容与长度需满足发帖校验，见报错提示" \
--image ./1.png --image ./2.png
xhs draft list --account agidaily
xhs draft show <草稿 id>
xhs draft approve <草稿 id>
# 仅当你确认要立即走浏览器发帖链路时：
xhs draft publish <草稿 id>成功后：草稿标记为 published，并在 published/ 写入一条 JSON 归档。
xhs published list --account agidaily与 xhs help 一致（节选）。
| 用法 | 说明 |
|---|---|
xhs |
交互模式：提示符 xhs> ，每行一条子命令 |
xhs help |
打印帮助 |
xhs account list |
列出账号（* 标当前默认） |
xhs account add <name> [--display-name …] [--role …] |
创建账号目录、browser-data、policy.md |
xhs account use <name> |
设为默认账号 |
xhs account current |
显示默认账号 |
xhs account show <name> |
显示单账号配置 |
xhs login [--account …] |
浏览器登录小红书 |
xhs metrics [--account …] |
创作者后台运营数据摘要 |
xhs posted [--account …] [--limit N] |
已发笔记列表 |
xhs note-detail <noteId> [--account …] |
笔记详情 |
xhs draft create … |
新建草稿 JSON |
xhs draft list [--account …] [--status …] |
草稿列表 |
xhs draft show <id> |
草稿详情 |
xhs draft approve <id> |
置为 approved |
xhs draft publish <id> |
对已批准草稿触发发帖（需真实浏览器环境） |
xhs published list [--account …] |
本地发布归档 |
xhs post \
--title "标题" \
--content "正文（须满足长度校验）" \
--image ./1.png \
--image ./2.jpg \
[--account agidaily] \
[--publish]--image至少 1 张、最多 18 张。--publish：填表后尝试自动点击「发布」（仍视页面实际状态而定）。
- 支持单引号/双引号包裹含空格的参数。
- 输入
help查看帮助，exit/quit退出；Ctrl+C 正常退出。
| 命令 | 作用 |
|---|---|
npm run build |
tsc 编译到 dist/ |
npm run dev |
先 build 再执行无参 xhs（进入交互模式） |
源码结构参见 src/config.ts 与各工具实现；AGENTS.md 供自动化编排参考。
本项目以 GNU General Public License v3.0（GPL-3.0）发布。