xhs-cli

在终端里使用的小红书工具：登录、创作者指标、创作者后台已发笔记（recent）、单篇笔记详情（detail）、本地发帖归档（posted），以及用标题 + 正文 + 本地图片路径在创作后台填表发帖（post，需本机 Chrome/Chromium）。

支持多账号隔离（每账号独立浏览器会话目录），适合与 Agent 或自动化流程编排配合；发帖仍以本地人机确认为前提。

依赖

• Node.js 20 及以上
• Chrome 或 Chromium（本机已安装；CLI 通过 Puppeteer 连接，不随包下载浏览器）

安装

npm install -g xhs-cli

安装后使用命令 xhs。完整子命令列表：xhs help。

快速开始

1. 添加账号并登录

账号名仅允许 [a-zA-Z0-9._-]+：

xhs account add my-account
xhs account use my-account
xhs login

login 成功后会自动把该账号记为当前账号。会话保存在 ~/.xhs-cli/.cache/accounts/<name>/browser-data。

2. 发帖（填表）

xhs post \
  --title "标题" \
  --content "正文至少十个字，须满足小红书长度校验" \
  --image ./cover.png

• --image 可重复，至少 1 张、最多 18 张；也可用 --content-file <路径> 代替 --content。
• 默认只填表，不会自动点击发布；加 --publish 会在填表后尝试点击页面「发布」按钮。
• 临时操作其他账号：--account other。

3. 查看数据

xhs metrics
xhs recent --limit 20
xhs detail <noteId>
xhs posted

当前账号

| 命令 | 说明 | |------|------| | xhs account use <name> | 设置当前账号（写入 registry.json） | | xhs account current | 打印当前账号 slug | | xhs account list | 列表中带 * 的为当前账号 |

业务命令默认使用当前账号，无需每次写账号参数。临时切换仅支持 --account <slug>。

未设置当前账号时，命令会提示先执行 xhs account use <name>。

命令一览

| 命令 | 说明 | |------|------| | xhs help | 打印帮助 | | xhs account list | 列出已配置账号 | | xhs account add <name> | 新建账号（首个账号会自动设为当前） | | xhs account show <name> | 查看单账号配置 | | xhs account use <name> | 设置当前账号 | | xhs account current | 显示当前账号 | | xhs login [--account <name>] | 登录创作者中心 | | xhs metrics [--account <name>] | 运营数据摘要 | | xhs recent [--limit N] [--account <name>] | 创作者后台已发笔记 | | xhs detail <noteId> [--account <name>] | 笔记详情 | | xhs posted [--account <name>] | 本地 published/ 归档列表 | | xhs post --title … (--content … \| --content-file …) --image … [--account <name>] | 创作页填表发帖 |

数据目录

默认路径：~/.xhs-cli/.cache/

| 路径 | 说明 | |------|------| | accounts/registry.json | 账号注册表（含 currentAccount） | | accounts/<name>/browser-data/ | 该账号 Chrome 会话（Cookie 等） | | published/ | 本地发帖归档 JSON（xhs posted） |

发帖说明

• 本工具不会在未经你确认的情况下向小红书发稿。
• xhs post 未加 --publish 时：填入标题、正文、图片后保持浏览器窗口，由你在页面中确认并发布。
• --publish 会尝试自动点击「发布」，是否成功以页面实际状态为准。

许可证

GNU General Public License v3.0（GPL-3.0）

链接

• 仓库：https://github.com/joohw/xhs-cli
• Issues：https://github.com/joohw/xhs-cli/issues