> 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/docs-as-code/gitbook-cli.md).

# GitBook CLI

通过命令行处理你的 GitBook 内容——登录、查询 API，并通过脚本或 AI 编程代理驱动文档工作流。

GitBook CLI（`@gitbook/cli`）是一款命令行工具，可让你直接在终端中操作 GitBook 内容和组织。

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

## 人工操作与智能体工作流

CLI 面向两种使用方式：

* **人工驱动** ——你在终端中输入命令来查询信息、编写一次性任务脚本，或手动管理集成。输出格式适合在交互式 shell 中阅读。
* **智能体编程** ——AI 编程智能体（Claude Code、Codex、Cursor 等）会代表你运行 CLI，作为更大型任务的一部分。机器可读输出（`--json`）和可预测的命令结构让智能体能够轻松调用命令、解析结果并串联执行。

{% hint style="info" %}
如果你想让 AI 智能体通过专门设计的协议，使用 GitBook API 创建和编辑内容，请参阅 [GitBook MCP](https://gitbook.com/docs/documentation/zh/docs-as-code/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` / `unpublish`）需要个人 API 令牌——浏览器（OAuth）会话无法执行这些操作。发布工作流请运行 `gitbook auth --token <token>` 。两种凭据可以同时使用，因此你可以日常通过浏览器登录，并在发布时使用令牌。
{% endhint %}

## 运行你的第一条命令

大多数命令由 GitBook API 生成，并按资源分组，例如 `organizations`, `spaces`, `collections`等。首先，列出你所属的组织：

```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 会选择合适的默认格式：在交互式终端中输出 pretty 格式；在输出通过管道传输或重定向时输出 YAML。使用 `--json` 显式指定 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 集成](https://gitbook.com/docs/developers/integrations/quickstart.md)的主要工具。使用以下命令搭建新项目：

```bash
gitbook integration new
```

然后使用 `gitbook integration dev` 在本地运行，并使用 `gitbook integration publish` 发布。完整的开发工作流程请参阅 [集成文档](https://gitbook.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
