Gitbook CLI

GitBook CLI

The gitbook command (from the @gitbook/cli npm package) builds and publishes integrations on GitBook.com and publishes OpenAPI specs to a GitBook organization. This is the integration-platform CLI, not the legacy gitbook-cli book builder.

Setup

Install globally to get the gitbook command anywhere:

npm install -g @gitbook/cli

Or run it without installing:

npx @gitbook/cli <command>

Authenticate before running any command that talks to GitBook (everything except help). Without a valid session, those commands will fail.

gitbook auth            # prompts for a token
gitbook auth --token=<token>   # non-interactive, use this in CI
gitbook whoami          # confirm the session and which account is active

Choosing the right command

Integration workflow

The common path for building and shipping an integration:

1. gitbook new <dir> to scaffold the integration locally.
2. gitbook dev to connect it to your GitBook editor and iterate with live updates.
3. gitbook publish to ship it (reads gitbook-manifest.yaml).
4. gitbook unpublish <integration-name> if you need to take it down.

Command reference

gitbook auth

Authenticate the CLI with a GitBook Developer API token. Generate a personal token in your GitBook Developer settings. Pass it non-interactively with --token=<token> (do this in CI so nothing is prompted); if no token is provided, the CLI prompts for one.

gitbook whoami

Print information about the currently authenticated user. Use it to confirm authentication succeeded or to check which account is active.

gitbook new <dir>

Create and initialize a new integration locally in <dir>. The CLI prompts for information about the integration.

gitbook dev

Open a live connection from your local integration to your GitBook editor. While the connection is running, changes you make locally are received in the editor automatically. See the development guide.

gitbook publish

Publish the integration defined in the gitbook-manifest.yaml file. See the GitBook Manifest reference for the manifest fields, and the publishing guide for how publishing works.

gitbook unpublish <integration-name>

Remove your integration from the GitBook integration platform. Pass the name of the integration as the argument.

gitbook openapi publish

gitbook openapi publish <path_to_spec.yaml> --spec <spec_name> --organization <organization_id>

Publish a new OpenAPI spec or update an existing one in your organization. Re-running the command with the same --spec name updates that spec in place, which is what makes it safe to run on every commit in a CI/CD pipeline. See the CI/CD with API blocks guide to learn more about documenting your API in GitBook.

gitbook help

List the available GitBook CLI commands and information on using them.

Notes

• Run gitbook auth (or pass --token) before new, dev, publish, unpublish, or openapi publish. Only help works without a session.
• In CI, prefer gitbook auth --token=$GITBOOK_TOKEN with the token stored as a secret, so no step blocks on an interactive prompt.
• publish always reads gitbook-manifest.yaml from the integration directory, so keep that file in sync with what you intend to ship.