Autogenerate CLI

[talagluck]

This adds gitbook2, a standalone CLI for exercising the GitBook API. It's a separate binary from the main gitbook CLI (which builds and publishes integrations) so I could develop the generated API commands in isolation without cluttering the stable command tree.

The command tree is generated from packages/api/spec/openapi.yaml by scripts/generate-commands.ts — one command per public operation, named off the URL path (e.g. gitbook2 organizations list, gitbook2 spaces get <id>). It shares auth/config with the main CLI, and ships shell completion for bash/zsh/fish.

Things that would be helpful for review:

• The approach - does this seem reasonable for autogenerating the CLI
• The output - dumping the full response for list commands was unreadable, so pretty output is now compact by default:
  • Lists print one line per item — id + name/title + a couple of identifying
    fields — with a footer showing the count and the pagination cursor as a
    ready-to-paste flag (next page: --page <cursor>).
  • Single objects show just the identifying fields, with a hint to use --full.
  • --full restores the complete dump, and --json / --yaml are untouched, so
    scripts and agents still get the full structured response. When piped (not a
    TTY) it defaults to YAML.
• Usage - I'm going to do a bunch of testing, but it would be great if others try this out and see how well it works for them!

I pulled the formatting logic into packages/cli/src/output.ts (instead of inlining it in the generated file) so it has a single source of truth and can be unit-tested directly — see output.test.ts (bun test).

A few notes:

• generated-commands.ts is auto-generated — don't hand-edit it; prebuild regenerates it from the spec via npm run generate-commands.
• gitbook2 / cli2 are working names for now — I'll rename before this goes in for real.
• Opening as a draft. I haven't added a changeset yet, and there are open questions on naming, so I'd rather get feedback on the shape first.
• Some additional things needed:
  • Incorporating the authentication changes we're working on
  • Incorporating commands from the current CLI which aren't autogenerated (like the ones for publishing integrations)
  • Usage stats

How to test gitbook2

Requires Node ≥18 and bun.

# 1. Get the branch
git fetch origin tal/cli_updates
git checkout tal/cli_updates

# 2. Install deps (from the repo root)
bun install

# 3. Build the CLI (regenerates commands from the spec, then bundles)
cd packages/cli
bun run build          # runs `generate-commands` via prebuild, then build.sh

# 4. Authenticate (create a token at https://app.gitbook.com/account/developer)
node dist/cli2.js auth
#   …or non-interactively:
#   node dist/cli2.js auth --token <YOUR_TOKEN>

Then run any command via node dist/cli2.js <command>:

# Compact, readable output (the default when attached to a terminal)
node dist/cli2.js organizations list
node dist/cli2.js spaces list --organization <orgId>
node dist/cli2.js organizations get <orgId>

# Escape hatches
node dist/cli2.js organizations list --full     # full pretty dump
node dist/cli2.js organizations list --json      # machine-readable (unchanged)
node dist/cli2.js organizations list --yaml      # machine-readable (default when piped)

# Pagination — the footer prints the exact flag to paste
node dist/cli2.js organizations list --page <cursor>

# Discover commands
node dist/cli2.js --help
node dist/cli2.js organizations --help

Optional: install and run it as gitbook2 instead of node dist/cli2.js

# from packages/cli
bun link                 # links the `gitbook2` bin onto your PATH
gitbook2 organizations list

Run the formatting unit tests

# from packages/cli
bun test

[changeset-bot]

⚠️ No Changeset found

Latest commit: a95be30

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

bun add https://pkg.pr.new/GitbookIO/integrations/@gitbook/api@1205

commit: a95be30