> 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/documentation-as-code/gitbook-cli.md). # GitBook CLI Le CLI GitBook (`@gitbook/cli`) est un outil en ligne de commande pour 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 — le tout sans quitter le shell. ## Flux de travail humains et agentiques Le CLI est conçu pour deux types d’utilisation : * **Piloté par l’humain** — vous tapez des commandes dans votre terminal pour rechercher des informations, automatiser des tâches ponctuelles ou gérer des intégrations manuellement. La sortie est formatée pour être lisible dans un shell interactif. * **Codage agentique** — un agent de codage IA (Claude Code, Codex, Cursor et similaires) exécute le CLI en votre nom dans le cadre d’une tâche plus vaste. Une sortie lisible par machine (`--json`) et une structure de commande prévisible permettent à un agent d’appeler 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 conçu à cet effet, voir [GitBook MCP](/docs/documentation/fr/documentation-as-code/gitbook-mcp.md). Le CLI est particulièrement adapté lorsque vous voulez des commandes scriptables, du développement d’intégrations, ou un agent qui fonctionne déjà confortablement dans un terminal. {% endhint %} ## Installer Le CLI GitBook nécessite Node v18 ou version ultérieure. Installez-le globalement depuis npm : ```bash npm install @gitbook/cli -g ``` Cela installe la `gitbook` commande. Vérifiez qu’elle fonctionne : ```bash gitbook --version ``` ## Authentifier Connectez-vous une fois et le CLI stocke vos identifiants localement, en les actualisant au besoin. {% 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, puis stocke localement le jeton obtenu. Les sessions sont actualisées automatiquement. C’est la méthode recommandée pour une utilisation quotidienne. {% endtab %} {% tab title="Jeton API personnel" %} Pour éviter le flux du navigateur — pour la CI, les scripts ou la publication d’intégrations — authentifiez-vous avec un jeton API personnel. Créez-en un sur [app.gitbook.com/account/developer](https://app.gitbook.com/account/developer), puis exécutez : ```bash gitbook auth --token ``` Si vous omettez `--token`, le CLI vous le demande. {% endtab %} {% endtabs %} Vérifiez à tout moment sous 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 API personnel — la session du navigateur (OAuth) ne peut pas effectuer ces opérations. Exécutez `gitbook auth --token ` pour les workflows de publication. Les deux identifiants peuvent coexister, vous pouvez donc utiliser la connexion via le navigateur pour les commandes quotidiennes 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 — `organisations`, `espaces`, `collections`, et ainsi de suite. Commencez par lister les organisations auxquelles vous appartenez : ```bash gitbook organizations list ``` Récupérez un identifiant d’organisation dans cette sortie, puis listez ses espaces : ```bash gitbook spaces list --organization ``` Récupérez les détails d’un espace unique : ```bash gitbook spaces get ``` Listez les pages d’un espace : ```bash gitbook spaces content pages list ``` {% hint style="info" %} Les paramètres de chemin comme `` peuvent être passés comme argument positionnel ou comme option — `gitbook spaces get ` et `gitbook spaces get --spaceId ` sont équivalents. {% 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 voir ses sous-commandes et 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 fournissez pas d’option, le CLI choisit une valeur par défaut raisonnable : une sortie lisible dans un terminal interactif, et YAML lorsque la sortie est acheminée ou redirigée. Utilisez `--json` explicitement lorsque vous redirigez 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 --query "How do I reset my password?" ``` La réponse s’affiche en continu dans votre terminal, suivie de ses sources et de questions de suivi suggérées. Appuyez sur `Ctrl-C` pour arrêter plus tôt et conserver tout ce qui a déjà été diffusé. ## Pilotez le CLI depuis un agent de codage IA Comme le CLI est scriptable et parle JSON, un agent de codage IA peut l’utiliser comme outil pendant son travail. Orientez votre agent vers les commandes ci-dessus et laissez-le s’authentifier, explorer votre contenu et agir en fonction des résultats. {% prompt description="Explore an organization’s docs from the terminal." %} ```markdown En utilisant le CLI `gitbook`, aidez-moi à m’orienter dans mon contenu GitBook. 1. Exécutez `gitbook whoami` pour confirmer que je suis connecté. Sinon, dites-moi d’exécuter `gitbook login`. 2. Listez mes organisations avec `gitbook organizations list --json` et montrez-moi les noms et les identifiants. 3. Demandez-moi quelle organisation explorer, puis listez ses espaces. 4. Résumez ce que vous trouvez — combien il y a d’espaces, et ce que chacun semble couvrir d’après son titre. Utilisez `--json` pour chaque commande afin de pouvoir analyser la sortie de manière fiable, et montrez-moi les commandes exactes que vous exécutez. ``` {% endprompt %} {% prompt description="Answer a question using my docs and cite sources." %} ```markdown En utilisant le CLI `gitbook`, répondez à une question tirée de ma documentation. 1. Confirmez que je suis connecté avec `gitbook whoami`. 2. Listez mes organisations et confirmez laquelle rechercher. 3. Exécutez `gitbook organizations ask stream --query ""` et transmettez la réponse. 4. Incluez 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à de l’interrogation du contenu, le CLI est l’outil principal pour développer [des intégrations GitBook](/docs/developers/integrations/quickstart.md). Générez la structure d’un nouveau projet avec : ```bash gitbook integration new ``` Puis utilisez `gitbook integration dev` pour l’exécuter en local et `gitbook integration publish` pour le déployer. Consultez la [documentation des intégrations](/docs/developers/integrations/quickstart.md) pour le workflow complet 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 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/fr/documentation-as-code/gitbook-cli.md?ask=&goal= ``` `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.