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

# GitBook CLI

Travaillez avec votre contenu GitBook depuis la ligne de commande — connectez-vous, interrogez l’API et pilotez les workflows de documentation à partir de scripts ou d’agents de codage IA.

La CLI GitBook (`@gitbook/cli`) est un outil en ligne de commande qui permet de travailler avec votre contenu et vos organisations GitBook directement depuis votre terminal.

Il encapsule l’API GitBook sous forme d’un ensemble de commandes, afin que vous puissiez lister les organisations, inspecter les espaces et les pages, poser des questions sur votre documentation, et créer et publier des intégrations — sans quitter le shell.

## Flux de travail humains et agentiques

Le CLI est conçu pour deux types d’utilisation :

* **Utilisation manuelle**  : vous saisissez des commandes dans votre terminal pour rechercher des informations, automatiser des tâches ponctuelles ou gérer des intégrations manuellement. La sortie est mise en forme pour être lisible dans un terminal interactif.
* **Programmation assistée par agent**  : un agent de programmation IA (Claude Code, Codex, Cursor et outils similaires) exécute la CLI pour vous dans le cadre d’une tâche plus vaste. Le format de sortie lisible par machine (`--json`) et la structure prévisible des commandes permettent à un agent d’exécuter facilement des commandes, d’analyser les résultats et de les enchaîner.

{% hint style="info" %}
Si vous souhaitez qu’un agent IA crée et modifie du contenu via l’API GitBook à l’aide d’un protocole dédié, consultez [GitBook MCP](https://gitbook.com/docs/documentation/fr/docs-as-code/gitbook-mcp.md). La CLI est adaptée si vous souhaitez disposer de commandes scriptables, développer des intégrations ou utiliser un agent qui maîtrise déjà le terminal.
{% endhint %}

## Installation

Le CLI GitBook nécessite Node v18 ou une version ultérieure. Installez-le globalement depuis npm :

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

Cette opération installe la commande `gitbook` . Vérifiez qu’elle fonctionne :

```bash
gitbook --version
```

## Authentification

Connectez-vous une fois et le CLI stocke vos identifiants localement, en les renouvelant si nécessaire.

{% tabs %}
{% tab title="Navigateur (OAuth)" %}
La façon la plus rapide de se connecter est via votre navigateur :

```bash
gitbook login
```

Cela ouvre GitBook dans votre navigateur, vous demande d’autoriser le CLI, et stocke le jeton obtenu localement. Les sessions sont renouvelées automatiquement.

C’est l’option recommandée pour un usage quotidien.
{% endtab %}

{% tab title="Jeton d’API personnel" %}
Pour ignorer la procédure via le navigateur — dans le cadre de l’intégration continue (CI), de scripts ou de la publication d’intégrations — authentifiez-vous avec un jeton d’API personnel. Créez-en un à l’adresse [app.gitbook.com/account/developer](https://app.gitbook.com/account/developer), puis exécutez :

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

Si vous omettez `--token`, la CLI vous invite à saisir le jeton.
{% endtab %}
{% endtabs %}

Vérifiez à tout moment avec quel compte vous êtes connecté :

```bash
gitbook whoami
```

Pour vous déconnecter, exécutez `gitbook logout`.

{% hint style="warning" %}
La publication d’intégrations (`gitbook integration publish` / `unpublish`) nécessite un jeton d’API personnel : la session du navigateur (OAuth) ne permet pas d’effectuer ces opérations. Exécutez `gitbook auth --token <token>` pour publier des intégrations. Les deux identifiants peuvent coexister : vous pouvez donc utiliser la connexion par navigateur pour les commandes courantes et un jeton pour la publication.
{% endhint %}

## Exécutez vos premières commandes

La plupart des commandes sont générées à partir de l’API GitBook et regroupées par ressource : `organizations`, `spaces`, `collections`, etc. Commencez par répertorier les organisations dont vous faites partie :

```bash
gitbook organizations list
```

Récupérez un identifiant d’organisation depuis cette sortie, puis listez ses espaces :

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

Récupérez les détails d’un espace unique :

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

Listez les pages d’un espace :

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

{% hint style="info" %}
Les paramètres de chemin tels que `<spaceId>` peuvent être transmis comme argument positionnel ou comme option : `gitbook spaces get <spaceId>` et `gitbook spaces get --spaceId <spaceId>` sont équivalentes.
{% endhint %}

Exécutez `gitbook --help` pour parcourir l’arborescence complète des commandes, ou ajoutez `--help` à n’importe quelle commande (par exemple `gitbook spaces --help`) pour afficher ses sous-commandes et ses options.

## Formats de sortie

Chaque commande de l’API prend en charge les mêmes options de sortie :

| Option     | Sortie                                                                 |
| ---------- | ---------------------------------------------------------------------- |
| `--pretty` | Résumés lisibles par l’humain (par défaut dans un terminal interactif) |
| `--json`   | JSON — idéal pour les scripts et les agents                            |
| `--yaml`   | YAML                                                                   |
| `--full`   | Afficher tous les champs au lieu du résumé compact                     |

Si vous ne transmettez aucun indicateur, l’interface en ligne de commande choisit une valeur par défaut adaptée : une sortie mise en forme dans un terminal interactif, et du YAML lorsque la sortie est redirigée ou envoyée vers un tube. Transmettez `--json` explicitement lorsque vous envoyez la sortie vers des outils comme `jq`:

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

## Posez une question à votre documentation

Le CLI peut interroger votre contenu en langage naturel et diffuser la réponse au fur et à mesure de sa génération :

```bash
gitbook organizations ask stream <organizationId> --query "Comment réinitialiser mon mot de passe ?"
```

La réponse s’affiche progressivement dans votre terminal, suivie de ses sources et de suggestions de questions complémentaires. Appuyez sur `Ctrl-C` pour interrompre l’affichage et conserver tout ce qui a été affiché jusque-là.

## Pilotez le CLI depuis un agent de codage IA

Parce que le CLI est scriptable et parle JSON, un agent de codage IA peut l’utiliser comme un outil pendant son travail. Donnez à votre agent les commandes ci-dessus et laissez-le s’authentifier, explorer votre contenu et agir sur les résultats.

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

```markdown
Avec le CLI `gitbook`, aide-moi à me familiariser avec mon contenu GitBook.

1. Exécute `gitbook whoami` pour confirmer que je suis connecté. Sinon, dis-moi d’exécuter `gitbook login`.
2. Liste mes organisations avec `gitbook organizations list --json` et montre-moi les noms et les identifiants.
3. Demande-moi quelle organisation explorer, puis liste ses espaces.
4. Résume ce que tu trouves — combien il y a d’espaces, et ce que chacun semble couvrir d’après son titre.

Utilise `--json` pour chaque commande afin de pouvoir analyser la sortie de manière fiable, et montre-moi les commandes exactes que tu exécutes.
```

{% endprompt %}

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

```markdown
Avec le CLI `gitbook`, réponds à une question à partir de ma documentation.

1. Confirme que je suis connecté avec `gitbook whoami`.
2. Liste mes organisations et confirme laquelle rechercher.
3. Exécute `gitbook organizations ask stream <organizationId> --query "<ma question>"` et relaie la réponse.
4. Inclue les sources renvoyées par le CLI afin que je puisse vérifier la réponse par rapport aux pages d’origine.
```

{% endprompt %}

## Créer des intégrations

Au-delà des requêtes sur le contenu, l’interface en ligne de commande est l’outil principal pour développer des [intégrations GitBook](https://gitbook.com/docs/developers/integrations/quickstart.md). Créez la structure d’un nouveau projet avec :

```bash
gitbook integration new
```

Utilisez ensuite `gitbook integration dev` pour l’exécuter localement, puis `gitbook integration publish` pour le publier. Consultez la [documentation sur les intégrations](https://gitbook.com/docs/developers/integrations/quickstart.md) pour découvrir l’ensemble du processus de développement.


---

# 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/fr/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.
