> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/gitbook-cli.md).

# GitBook CLI

GitBook CLI（`@gitbook/cli`）是一个命令行工具，可直接从终端处理你的 GitBook 内容和组织。

它将 GitBook API 封装为一组命令，因此你可以列出组织、查看空间和页面、向文档提问，以及构建并发布集成——所有操作都无需离开命令行。

## 人工与代理工作流

该 CLI 面向两种使用方式：

* **人工驱动** ——你在终端中输入命令来查询信息、编写一次性任务脚本，或手动管理集成。输出经过格式化，便于在交互式 shell 中阅读。
* **代理式编码** ——由 AI 编码代理（Claude Code、Codex、Cursor 及类似工具）代表你运行 CLI，作为更大任务的一部分。机器可读输出（`--json`）和可预测的命令结构，使代理能够轻松调用命令、解析结果并将它们串联起来。

{% hint style="info" %}
如果你希望 AI 代理使用专门构建的协议通过 GitBook 的 API 创建和编辑内容，请参阅 [GitBook MCP](/docs/documentation/zh/wen-dang-ji-dai-ma/gitbook-mcp.md)。当你需要可脚本化命令、集成开发，或希望代理本身就能在终端中自如工作时，CLI 是很合适的选择。
{% endhint %}

## 安装

GitBook CLI 需要 Node v18 或更高版本。请从 npm 全局安装：

```bash
npm install @gitbook/cli -g
```

这将安装 `gitbook` 命令。检查它是否可用：

```bash
gitbook --version
```

## Authenticate

只需登录一次，CLI 就会在本地存储你的凭据，并在需要时自动刷新。

{% tabs %}
{% tab title="浏览器（OAuth）" %}
登录最快的方式是通过浏览器：

```bash
gitbook login
```

这会在浏览器中打开 GitBook，要求你授权 CLI，并将生成的令牌保存在本地。会话会自动刷新。

这是日常使用的推荐方式。
{% endtab %}

{% tab title="个人 API 令牌" %}
若要跳过浏览器流程——用于 CI、脚本或发布集成——请使用个人 API 令牌进行身份验证。请在以下位置创建一个： [app.gitbook.com/account/developer](https://app.gitbook.com/account/developer)，然后运行：

```bash
gitbook auth --token <token>
```

如果你省略 `--token`，CLI 会提示你输入它。
{% endtab %}
{% endtabs %}

你可以随时确认当前登录的是谁：

```bash
gitbook whoami
```

要退出登录，请运行 `gitbook logout`.

{% hint style="warning" %}
发布集成（`gitbook integration publish` / `取消发布`）需要个人 API 令牌——浏览器（OAuth）会话无法执行这些操作。请为 `gitbook auth --token <token>` 发布工作流运行。两种凭据可以共存，因此你可以使用浏览器登录来执行日常命令，并使用令牌进行发布。
{% endhint %}

## 运行你的第一个命令

大多数命令都是从 GitBook API 生成并按资源分组的—— `组织`, `空间`, `集合`，等等。先列出你所属的组织：

```bash
gitbook organizations list
```

从该输出中获取一个组织 ID，然后列出其空间：

```bash
gitbook spaces list --organization <organizationId>
```

获取单个空间的详细信息：

```bash
gitbook spaces get <spaceId>
```

列出某个空间中的页面：

```bash
gitbook spaces content pages list <spaceId>
```

{% hint style="info" %}
路径参数，例如 `<spaceId>` 可以作为位置参数或标志传递—— `gitbook spaces get <spaceId>` 并 `gitbook spaces get --spaceId <spaceId>` 是等价的。
{% endhint %}

运行 `gitbook --help` 来浏览完整的命令树，或者在任何命令后添加 `--help` （例如 `gitbook spaces --help`）即可查看其子命令和选项。

## 输出格式

每个 API 命令都支持相同的输出标志：

| 标志         | 输出                  |
| ---------- | ------------------- |
| `--pretty` | 人类可读摘要（在交互式终端中为默认值） |
| `--json`   | JSON——最适合脚本和代理      |
| `--yaml`   | YAML                |
| `--full`   | 显示每个字段，而不是简要摘要      |

如果你不传递任何标志，CLI 会选择合理的默认值：在交互式终端中输出美化内容，而在输出被管道传输或重定向时输出 YAML。使用 `--json` 在将输出管道传给诸如 `jq`:

```bash
gitbook organizations list --json | jq '.items[].title'
```

## 向你的文档提一个问题

CLI 可以使用自然语言查询你的内容，并在答案生成时流式返回：

```bash
gitbook organizations ask stream <organizationId> --query "How do I reset my password?"
```

答案会流式输出到你的终端，随后是其来源和建议的后续问题。按 `Ctrl-C` 可提前停止，并保留已流式输出的内容。

## 让 AI 编码代理驱动 CLI

由于 CLI 可脚本化并支持 JSON，AI 编码代理可以在工作时将其作为工具使用。让你的代理使用上面的命令，并让它进行身份验证、探索你的内容并基于结果采取行动。

{% prompt description="Explore an organization’s docs from the terminal." %}

```markdown
使用 `gitbook` CLI，帮我快速熟悉我的 GitBook 内容。

1. 运行 `gitbook whoami` 确认我已登录。如果没有，请告诉我运行 `gitbook login`。
2. 使用 `gitbook organizations list --json` 列出我的组织，并显示它们的名称和 ID。
3. 询问我要探索哪个组织，然后列出其空间。
4. 总结你找到的内容——有多少个空间，以及根据标题看每个空间大致涵盖什么。

对每个命令都使用 `--json`，这样你就能可靠地解析输出，并向我展示你运行的确切命令。
```

{% endprompt %}

{% prompt description="Answer a question using my docs and cite sources." %}

```markdown
使用 `gitbook` CLI，回答我文档中的一个问题。

1. 使用 `gitbook whoami` 确认我已登录。
2. 列出我的组织，并确认要搜索哪个组织。
3. 运行 `gitbook organizations ask stream <organizationId> --query "<my question>"` 并转述答案。
4. 包含 CLI 返回的来源，这样我可以对照原始页面验证答案。
```

{% endprompt %}

## 构建集成

除了查询内容之外，CLI 还是开发 [GitBook 集成的主要工具](/docs/developers/integrations/quickstart.md)。使用以下命令搭建新项目：

```bash
gitbook integration new
```

然后使用 `gitbook integration dev` 在本地运行它，并使用 `gitbook integration publish` 来发布它。请参阅 [集成文档](/docs/developers/integrations/quickstart.md) 了解完整的开发流程。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/gitbook-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.