zsxq-cli

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)