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

# GitBook CLI

コマンドラインから GitBook のコンテンツを操作します。サインイン、API のクエリ、スクリプトや AI コーディングエージェントによるドキュメントワークフローの実行ができます。

GitBook CLI（`@gitbook/cli`）は、ターミナルから GitBook のコンテンツや組織を直接操作するためのコマンドラインツールです。

GitBook API を一連のコマンドとして利用できるため、シェルを離れることなく、組織の一覧表示、スペースやページの確認、ドキュメントに関する質問、インテグレーションの構築と公開を行えます。

## 人間とエージェントによるワークフロー

CLI は、次の 2 種類の利用方法を想定して設計されています。

* **人間主導** — ターミナルでコマンドを入力し、情報を調べたり、単発のタスクをスクリプト化したり、インテグレーションを手動で管理したりします。出力は、対話型シェルで読みやすい形式で表示されます。
* **エージェントによるコーディング** — AI コーディングエージェント（Claude Code、Codex、Cursor など）が、より大きなタスクの一環として CLI を実行します。機械可読な出力（`--json`）と予測しやすいコマンド構成により、エージェントはコマンドを実行して結果を解析し、それらを連携させやすくなります。

{% hint style="info" %}
専用プロトコルを使って、AIエージェントにGitBookのAPI経由でコンテンツを作成・編集させたい場合は、 [GitBook MCP](https://gitbook.com/docs/documentation/ja-gitbook-documentation/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>` を実行して、公開ワークフローに使用します。2 種類の認証情報は併用できるため、通常のコマンドにはブラウザーでサインインし、公開にはトークンを使用できます。
{% 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` を明示的に指定すると、次のようなツールにパイプで渡せます。 `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/ja-gitbook-documentation/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.
