yuque-cli 2.3.0

针对语雀的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD

yuque-cli

语雀通用命令行客户端，以浏览器 cookie 认证，驱动语雀内部 web 接口，提供文档与评论的增删改查。

术语（知识库/文档/评论/space/namespace/slug）见 CONTEXT.md；关键设计取舍见 docs/adr。

安装

需要 Python ≥ 3.10 与 uv。

uv sync                 # 安装依赖
uv run yuque --help     # 项目内运行
uv tool install .       # 全局安装

快速开始

yuque auth login                       # 登录（自动 CDP 抓取 cookie，失败回退手动粘贴）
yuque auth status                      # 查看当前身份
yuque repo list                        # 列出我的知识库
yuque doc list  <space>/<repo>         # 列出知识库下的文档
yuque doc get   <space>/<repo>/<slug>  # 取文档正文（Markdown）

地址可用完整浏览器 URL 或去掉 host 的路径形态，二者等价。

认证

yuque auth login 默认从 Chrome 远程调试端口（9222）自动抓取 cookie。未检测到远程调试时，自动降级为手动粘贴 cookie。也可 yuque auth login --manual 跳过 CDP，或 yuque auth login --cookie "..." 直接传入。

会话保存在 ~/.config/yuque-cli/session.json（权限 0600），yuque auth logout 清除。

全局选项

置于子命令之前：yuque --json repo list。

选项	说明
--json	输出原始 JSON
-y, --yes	跳过确认
-v, --verbose	打印 HTTP 请求到 stderr
-V, --version	显示版本

命令

auth

命令	说明
auth login [--manual]	登录
auth status	显示当前身份
auth logout	清除会话

repo

命令	说明
repo list	列出我的知识库
repo get <space>/<repo>	获取知识库信息
repo toc <space>/<repo>	获取知识库的文档目录树

doc

命令	说明
doc list <space>/<repo>	列出文档
doc get <space>/<repo>/<slug>	取正文（默认 Markdown，--json 出详情）
doc create <space>/<repo> -t <标题> [选项]	创建文档
doc update <space>/<repo>/<slug> [选项]	更新文档（先取后合并，未给的字段保持原值）
doc delete <space>/<repo>/<slug>	删除文档（软删，可回收站恢复）

doc create 选项：-t/--title（必填）、--slug、--public/--private、-b/--body、-F/--file。

doc update 选项：-t/--title、--public/--private、-b/--body、-F/--file；至少给其一。

正文中可直接写 @用户名（login 或中文名），CLI 自动搜索用户并转为语雀 @ 提及卡片。

yuque doc create team/handbook -t "上手指南" --body "# 标题\n正文"
yuque doc create team/handbook -t "周报" -F report.md --private
yuque doc create team/handbook -t "评审" --body "@suricatta 请审核这份文档"
yuque doc update team/handbook/getting-started -t "新标题"
yuque -y doc delete team/handbook/old-draft

comment

命令	说明
comment list <space>/<repo>/<slug>	列出评论
comment create <space>/<repo>/<slug> [-b/--body | -F/--file]	添加评论
comment delete <comment_id>	删除评论

正文输入

doc create / comment create 正文来源（--body 与 --file 互斥）：

1. -b/--body 内联字符串
2. -F/--file 从文件读（-F - 读 stdin）
3. 管道 stdin

echo "# 正文" | yuque doc create team/handbook -t "标题"

doc update 只有显式给 -b/-F 才会改正文，裸管道不生效。

环境变量

变量	作用	默认
YUQUE_HOST	目标语雀 host	www.yuque.com
YUQUE_CONFIG_DIR	配置目录	~/.config/yuque-cli
NO_COLOR	禁用彩色输出	—

开发

mise run deps     # uv sync
mise run test     # pytest
mise run lint     # ruff check && ruff format
mise run check    # pyright
mise run cli -- --help