# Gitbook CLI

> How to use the GitBook CLI (the `gitbook` command from the @gitbook/cli package) to authenticate, scaffold and develop GitBook integrations, publish and unpublish them, check the authenticated user, and publish or update OpenAPI specs to a GitBook organization (including from CI/CD). Use this skill whenever the user runs or asks about any `gitbook` subcommand (auth, new, dev, publish, unpublish, whoami, openapi publish), is building or shipping a GitBook integration, edits a gitbook-manifest.yaml, or needs to push an OpenAPI specification to GitBook, even if they don't mention the CLI by name.

- Skill: `gitbookio/gitbook-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gitbookio/gitbook-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitbookio/gitbook-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gitbookio (https://skillmd.com/u/gitbookio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gitbookio/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:

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

Or run it without installing:

```bash
npx @gitbook/cli <command>
```

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

```bash
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

| Goal | Command |
| --- | --- |
| Authenticate / log in | `gitbook auth` |
| Check who is logged in | `gitbook whoami` |
| Start a new integration | `gitbook new <dir>` |
| Develop with a live link to the editor | `gitbook dev` |
| Publish an integration | `gitbook publish` |
| Remove a published integration | `gitbook unpublish <integration-name>` |
| Publish or update an OpenAPI spec | `gitbook openapi publish <spec.yaml> --spec <name> --organization <org-id>` |
| List all commands | `gitbook help` |

## 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](https://app.gitbook.com/account/developer). 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](https://gitbook.com/docs/developers/integrations/development).

### `gitbook publish`

Publish the integration defined in the `gitbook-manifest.yaml` file. See the [GitBook Manifest reference](https://gitbook.com/docs/developers/integrations/configurations) for the manifest fields, and the [publishing guide](https://gitbook.com/docs/developers/integrations/publishing) 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`

```bash
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](https://gitbook.com/docs/api-references/guides/support-for-ci-cd-with-api-blocks) to learn more about documenting your API in GitBook.

| Argument | Description |
| --- | --- |
| `<path_to_spec.yaml>` | Path to the local OpenAPI specification file to publish. |
| `--spec <spec_name>` | Name/slug of the spec in your organization. Reuse the same name to update an existing spec. |
| `--organization <organization_id>` | The GitBook organization the spec belongs to. |

### `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.