# CLI 参考

> rooqi 命令——status、list、read、run 与 pdf——的输入格式与退出码。

- Source: https://rooqi.cn/zh-hans/docs/developers/cli-reference/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: RooQi Mac 1.0 测试版本 · 桥接协议 v1
- Status: 预览——尚未公开发布
- Last verified: 2026-10-26，依据 Apps/RooQiMac/IPC/Sources/RooQiBridge/Main.swift
- Known limitations: 每个 CLI 进程都是一次新连接，需要单独批准。批量输入最多 16 个请求、262,144 字节。

```text
rooqi status | list | read DOCUMENT_UUID | run < commands.json | pdf < pdf-commands.json | mcp
```

每条命令按行向标准输出写出 JSON [响应信封](/zh-hans/docs/developers/errors/)。

## 命令

### rooqi status

检查连接。`code` 为 `ready` 时退出码 `0`，否则 `1`。

### rooqi list

请求读取授权，等待批准（最多 120 秒），然后列出已授权文稿。

### rooqi read DOCUMENT_UUID

请求读取授权并等待批准，然后输出一份文稿的已保存文字。UUID 格式错误时以 `64` 退出。

### rooqi run

从标准输入读取 **1–16 个请求对象组成的 JSON 数组**，请求创建/追加授权并等待批准，然后按顺序执行。允许的方法：`createNote`、`appendText`。遇到第一个非 `ready` 响应即停止。

### rooqi pdf

与 `run` 相同，但请求 PDF 批注授权。允许的方法：`listApprovedDocuments`、`listPDFTargets`、`readPDFPage`、`annotatePDF`、`queryPDFOperation`。

### rooqi mcp

在 stdio 上启动 MCP 服务。见 [MCP 工具参考](/zh-hans/docs/developers/mcp-reference/)。

## 请求对象

`run` 或 `pdf` 批量中的每个对象都是一个协议请求：

| 字段 | 何时需要 | 说明 |
|---|---|---|
| `version` | 全部 | 固定为 `1` |
| `requestID` | 全部 | UUID，每个请求唯一 |
| `method` | 全部 | 见上文 |
| `mutation` | `createNote`、`appendText` | `{operationID, documentID, title?, text?, expectedVersion?, provider, model, promptVersion}` |
| `documentID` | `listPDFTargets`、`queryPDFOperation` | UUID |
| `pdfQuery` | `readPDFPage` | `{documentID, surfaceID, pageIndex, rect}` |
| `pdfAnnotation` | `annotatePDF` | 与 MCP `rooqi_annotate_pdf` 输入字段相同 |
| `operationID` | `queryPDFOperation` | UUID |

`createNote` 的 `mutation` 含 `title`（1–200 个字符），不含 `text` 与 `expectedVersion`；`appendText` 含 `text`（1–6,000 字节）与 `expectedVersion`，不含 `title`。未知字段会被拒绝。

## 退出码

| 代码 | 含义 |
|---|---|
| `0` | 全部响应均为 `ready` |
| `1` | 存在非 `ready` 响应（包括批准被拒或等待超时） |
| `64` | 用法错误或输入无效 |

## 示例

```sh
cat > commands.json <<'JSON'
[
  {
    "version": 1,
    "requestID": "8E0B7C1E-7B53-4C39-9A55-2B9F2C1E0A01",
    "method": "createNote",
    "mutation": {
      "operationID": "5C3D8F0A-2E6B-4F1C-8D7A-9B0E1F2A3B4C",
      "documentID": "0F1E2D3C-4B5A-4968-8776-655443322110",
      "title": "阅读笔记",
      "provider": "my-script",
      "model": "none",
      "promptVersion": "1"
    }
  }
]
JSON
rooqi run < commands.json
```

窗口出现时在 RooQi 中批准。请保留 `commands.json`：如果结果不确定，再次运行同一文件即可——同一个 `operationID` 不会重复写入。