> 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). # CLI GitBook Le CLI GitBook (`@gitbook/cli`) est un outil en ligne de commande permettant 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 — 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 à la main. La sortie est formatée pour être lisible dans un shell interactif. * **Codage agentique** — un agent de codage IA (Claude Code, Codex, Cursor et autres similaires) exécute le CLI en votre nom dans le cadre d’une tâche plus large. La sortie lisible par machine (`--json`) et la structure prévisible des commandes facilitent l’appel des commandes par un agent, l’analyse des résultats et leur enchaînement. {% 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é, voir [MCP de GitBook](/docs/documentation/fr/documentation-as-code/gitbook-mcp.md). Le CLI est un bon choix lorsque vous voulez des commandes scriptables, développer des intégrations ou utiliser un agent qui fonctionne déjà confortablement dans un 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 ``` 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 si nécessaire. {% tabs %} {% tab title="Navigateur (OAuth)" %} Le moyen le 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 actualisées automatiquement. C’est la méthode recommandée pour une utilisation quotidienne. {% endtab %} {% tab title="Jeton API personnel" %} Pour éviter le flux via navigateur — pour le 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 navigateur (OAuth) ne peut pas effectuer ces opérations. Exécutez `gitbook auth --token ` pour les flux de publication. Les deux identifiants peuvent coexister, vous pouvez donc utiliser la connexion via navigateur pour les commandes quotidiennes et un jeton pour publier. {% 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 ID 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 en argument positionnel ou via un indicateur — `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 indicateurs de sortie : | Indicateur | 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 chaque champ au lieu du résumé compact | Si vous ne fournissez pas d’indicateur, le CLI choisit une valeur par défaut raisonnable : une sortie lisible dans un terminal interactif, et YAML lorsque la sortie est envoyée via un pipe ou redirigée. Utilisez `--json` explicitement lorsque vous effectuez un pipe 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 "Comment réinitialiser mon mot de passe ?" ``` 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 ce qui a déjà été diffusé. ## 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 outil pendant qu’il travaille. Indiquez à 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 En utilisant le CLI `gitbook`, aide-moi à me repérer dans 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 ID. 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 façon fiable, et montre-moi les commandes exactes que tu exécutes. ``` {% endprompt %} {% prompt description="Answer a question using my docs and cite sources." %} ```markdown En utilisant le CLI `gitbook`, réponds à une question tirée de ma documentation. 1. Confirme que je suis connecté avec `gitbook whoami`. 2. Liste mes organisations et confirme laquelle chercher. 3. Exécute `gitbook organizations ask stream --query ""` 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à 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 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 connaître l’ensemble du flux 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.