Metadata-Version: 2.4
Name: yuque-cli
Version: 2.1.0
Summary: 针对语雀的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: websocket-client>=1.9.0
Description-Content-Type: text/markdown

# yuque-cli

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

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

## 安装

需要 Python ≥ 3.10 与 [uv](https://docs.astral.sh/uv/)。

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

## 快速开始

```bash
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`；至少给其一。

```bash
yuque doc create team/handbook -t "上手指南" --body "# 标题\n正文"
yuque doc create team/handbook -t "周报" -F report.md --private
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

```bash
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` | 禁用彩色输出 | — |

## 开发

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