zsxq-cli

知识星球 官方命令行工具:在终端发帖、评论、回答提问、记笔记、查看星球动态。

为什么选择 zsxq-cli

• 官方出品：知识星球团队维护，数据接口稳定，不依赖抓包或 cookie 注入
• OAuth 2.0 安全登录：设备授权流程 + 系统钥匙串（macOS Keychain / Linux Secret Service / Windows Credential Manager）加密存储，不在配置文件中保存明文 token
• AI Agent 原生支持：配套官方 Skill，可直接被 Claude Code、Cursor 等 AI 工具调用，无需额外配置
• 跨平台单文件二进制：Go 编译，冷启动快，macOS / Linux / Windows 全架构覆盖
• 脚本友好：所有命令支持 --json 输出，语义化退出码（0/1/2/5/11/13），适合嵌入 CI、cron、shell 脚本

Shell 补全

安装后可启用命令补全，支持 <TAB> 自动提示子命令和参数。

Zsh

mkdir -p ~/.zfunc
zsxq-cli completion zsh > ~/.zfunc/_zsxq-cli
# 确保 ~/.zshrc 中有：fpath=(~/.zfunc $fpath) && autoload -Uz compinit && compinit

Bash

zsxq-cli completion bash > ~/.bash_completion

Fish

zsxq-cli completion fish > ~/.config/fish/completions/zsxq-cli.fish

PowerShell

zsxq-cli completion powershell > zsxq-cli.ps1
. .\zsxq-cli.ps1

以上命令仅对当前会话生效。如需永久启用，将上述两行写入 $PROFILE（通常为 ~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1）。

安装

npm（推荐）

# 无需全局安装，直接 npx
npx zsxq-cli@latest auth login

# 或全局安装
npm install -g zsxq-cli

Homebrew

brew tap unnoo/tap
brew install zsxq-cli

30 秒上手

# 1. 登录（浏览器扫码授权，token 存入系统钥匙串）
zsxq-cli auth login

# 2. 查看当前身份
zsxq-cli user +info

# 3. 列出你加入的星球
zsxq-cli group +list

# 4. 发一条图文主题
zsxq-cli topic +create \
  --group-id <id> \
  --text "今天的思考……" \
  --files photo.jpg,report.pdf

# 5. 需要机器可读？所有命令都支持 --json
zsxq-cli group +list --json | jq '.[] | .name'

与 AI Agent 集成

通过配套官方 Skill，可直接接入 Claude Code、Cursor 等 AI 工具，让 AI 直接帮你：

• 按关键词检索历史主题、导出精华内容
• 批量整理、归档、备份星球内容
• 自动回答常见提问，草拟回复
• 生成周报、月报、活跃度统计

配套 skill 仓库：https://github.com/unnoo/zsxq-skill
官方介绍站：https://garden.zsxq.com/skill/

命令总览

账号与配置

| 命令 | 说明 | |------|------| | auth login | OAuth 设备授权登录 | | auth logout | 清除本地凭据 | | auth status | 查看登录状态 | | config show | 查看当前配置 | | doctor | 环境自检 |

星球（group）

| 命令 | 说明 | |------|------| | group +list | 列出我加入的星球 | | group +topics | 浏览星球主题流 | | group +hashtags | 查询星球标签 |

主题（topic）

| 命令 | 说明 | |------|------| | topic +search | 关键词搜索主题 | | topic +detail | 查看主题详情 | | topic +create | 发布主题（支持图片/文件） | | topic +edit | 编辑已发主题 | | topic +reply | 评论主题 | | topic +answer | 回答提问 |

笔记（note）

| 命令 | 说明 | |------|------| | note +create | 创建笔记 | | note +list | 列出笔记 | | note +detail | 查看笔记详情 | | note +edit | 编辑笔记 | | note +delete | 删除笔记 |

用户（user）

| 命令 | 说明 | |------|------| | user +info | 查看个人信息 | | user +footprints | 查看发帖足迹 |

高级：直接调用 API

zsxq-cli api list                    # 列出可用 API
zsxq-cli api call <name> --args ...  # 结构化调用
zsxq-cli api raw <method> ...        # 透传 JSON-RPC

完整命令请运行 zsxq-cli --help 或查看 官方文档。

对比

| | 手写脚本（cookie / requests） | zsxq-cli | |---|---|---| | 鉴权 | 手动抓 cookie，易失效 | OAuth 2.0 设备授权，一次登录长期有效 | | 凭据存储 | 明文写在脚本或 .env | 系统钥匙串加密存储 | | 接口稳定性 | 依赖非官方抓包 | 官方维护，接口变更有迁移保障 | | AI Agent 集成 | 需自己封装工具，维护成本高 | 配套官方 Skill，开箱即用 | | 跨平台 | Python/Node 运行时依赖 | 单文件二进制，冷启动 < 100ms | | 合规风险 | 可能违反使用条款 | 官方出品，合规可控 |

支持平台

| 平台 | 架构 | |------|------| | macOS | arm64 / x64 | | Linux | x64 / arm64 | | Windows | x64 / arm64 |

二进制通过 npm optionalDependencies 按平台分发，安装时自动选择当前平台的包，不会下载多余文件。

退出码

| 码 | 含义 | |----|------| | 0 | 成功 | | 1 | 网络错误 | | 2 | 参数/校验错误 | | 5 | 内部错误 | | 11 | 未登录或 token 失效 | | 13 | 权限不足 |

脚本中可据此做重试或分支逻辑。

反馈与贡献

• 官网：https://garden.zsxq.com/skill/
• Issue：https://github.com/unnoo/zsxq-skill/issues
• npm：https://www.npmjs.com/package/zsxq-cli

更新日志

v0.4.7

• 移除 npm 包的 postinstall 脚本,改为运行时定位平台二进制,无需安装期写文件,消除 Socket 供应链告警

v0.4.6

• 新增 user +nps 命令，支持提交 NPS 反馈评分与建议
• api list 改为实时从服务端拉取工具列表，自动同步最新工具
• 优化 api call --help，按分类列出所有可用工具示例
• 优化 api raw --help，新增点赞接口示例

v0.4.5

• 修复 Homebrew 安装方式检测逻辑，提升安装稳定性

License

Apache-2.0 © 知识星球 (ZSXQ)