@kubb/cli

The command-line interface for Kubb

Official CLI for Kubb. Run kubb generate to produce TypeScript types, API clients, hooks, validators, and mocks. Includes interactive project setup (kubb init), spec validation, watch mode, and an MCP server.

Installation

bun add -D @kubb/cli
# or
pnpm add -D @kubb/cli
# or
npm install -D @kubb/cli

Commands

• kubb init — scaffold a new project
• kubb generate — run code generation
• kubb studio — connect this project to Kubb Studio
• kubb validate — validate an OpenAPI spec
• kubb mcp — start the MCP server for AI assistants

kubb init

Scaffold a kubb.config.ts and install plugins for code generation from an OpenAPI spec. Run without flags for an interactive setup wizard, or pass flags to skip the prompts.

npx kubb init

Options

| Flag | Short | Type | Default | Description | | ------------------ | ----- | ------- | ---------------- | ------------------------------------------ | | --yes | -y | boolean | false | Skip all prompts and use defaults | | --input <path> | -i | string | ./openapi.yaml | Path to the OpenAPI specification | | --output <path> | -o | string | ./src/gen | Output directory for generated files | | --plugins <list> | | string | | Comma-separated list of plugins to install |

Available plugin values for --plugins: plugin-ts, plugin-axios, plugin-fetch, plugin-react-query, plugin-vue-query, plugin-zod, plugin-faker, plugin-msw, plugin-cypress, plugin-mcp, plugin-redoc.

Examples

# Interactive wizard
npx kubb init

# Accept all defaults
npx kubb init --yes

# Fully non-interactive
npx kubb init --input ./openapi.yaml --output ./src/gen --plugins plugin-ts,plugin-zod

# Select specific plugins only
npx kubb init --plugins plugin-ts,plugin-axios,plugin-react-query

The wizard will:

1. Detect or create a package.json if one does not exist
2. Prompt for your OpenAPI specification path (default: ./openapi.yaml)
3. Ask for the output directory (default: ./src/gen)
4. Let you choose which plugins to install
5. Install the selected packages using your package manager (npm, pnpm, yarn, or bun)
6. Generate a kubb.config.ts with your chosen configuration

kubb generate

Generate TypeScript types, API clients, React Query hooks, Zod schemas, and more from an OpenAPI specification. Reads kubb.config.ts by default. Pass an OpenAPI file path as the first argument to override the input without editing the config.

npx kubb generate

Options

| Flag | Short | Type | Default | Description | | --------------------- | ----- | ------- | ------- | ----------------------------------------------------------------------------------------------------------- | | [input] | | string | | OpenAPI file path or URL that overrides input in the config | | --config <path> | -c | string | | Path to the Kubb config file | | --log-level <level> | -l | string | info | Log level: silent, info, or verbose | | --watch | -w | boolean | false | Re-generate whenever the input file changes | | --verbose | -v | boolean | false | Override log level to verbose | | --silent | -s | boolean | false | Override log level to silent | | --reporter <names> | | string | cli | Reporters that render the run, comma-separated: cli, json, file, html. Overrides config.reporters |

Examples

# Use kubb.config.ts in the current directory
npx kubb generate

# Override the input spec without editing the config
npx kubb generate ./openapi.yaml

# Point to a custom config file
npx kubb generate --config ./configs/kubb.config.ts

# Watch for changes and regenerate automatically
npx kubb generate --watch

# Verbose output
npx kubb generate --verbose

# Write a JSON run report alongside the CLI output
npx kubb generate --reporter cli,json

# Write an HTML run report
npx kubb generate --reporter html

kubb studio

Connect this project to Kubb Studio and generate from the browser. Kubb runs on your machine, reads your config and spec from disk, and streams progress and files back to Studio over a WebSocket.

npx kubb studio

The first run pairs the machine. The CLI prints a short code, you approve it in Studio, and the CLI stores the agent token in ~/.kubb/credentials.json at mode 0600. Later runs reuse it. Set KUBB_HOME to store it, the machine secret, and the session registry somewhere other than ~/.kubb.

The connection is read-only by default. On the first connect to a project the CLI asks yes/no for each permission separately: writing generated files, editing kubb.config.ts, accepting a spec from Studio, and running the formatter, linter, or postGenerate. Each --allow-* flag skips the question for that one permission.

Arguments

| Argument | Required | Description | | ---------- | -------- | -------------------------------------------------- | | [action] | No | connect (default), login, logout or status |

Options

| Flag | Short | Type | Default | Description | | --------------------- | ----- | ------- | --------------------- | --------------------------------------------------------------------------------------------- | | --config <path> | -c | string | | Path to the Kubb config file | | --url <url> | | string | https://kubb.studio | Base URL of the Kubb Studio instance | | --allow-write | | boolean | false | Write generated files to disk. Asked for once per project when omitted | | --allow-config-edit | | boolean | false | Edit plugin options in kubb.config.ts. Asked for once per project when omitted | | --allow-exec | | boolean | false | Run the formatter, the linter, and output.postGenerate. Asked once per project when omitted | | --no-open | | boolean | | Do not open the approval page in a browser while pairing | | --log-level <level> | -l | string | info | Log level: silent, info, or verbose |

The old camelCase spelling of a flag (--allowWrite, --logLevel, --dryRun) still works and prints a deprecation warning on stderr. Support for it will be removed in a future major version.

Examples

# Pair on first run, then connect read-only
npx kubb studio

# Let Studio write generated files to disk
npx kubb studio --allow-write

# Pair without connecting
npx kubb studio login

# Show which machine is paired, and with which Studio
npx kubb studio status

# Forget the stored token
npx kubb studio logout

# Point at a self-hosted Studio
npx kubb studio --url http://localhost:3000

kubb validate

Parse and validate an OpenAPI/Swagger file for structural correctness. Reports schema errors, missing required fields, and malformed references. Use this before running generate to catch spec issues early.

npx kubb validate <path-or-url>

Arguments

| Argument | Required | Description | | --------- | -------- | --------------------------------------------------- | | <input> | ✅ | Path or URL to the OpenAPI/Swagger file to validate |

Examples

# Validate a local file
npx kubb validate ./openapi.yaml

# Validate a remote spec
npx kubb validate https://petstore3.swagger.io/api/v3/openapi.json

kubb mcp

Start a Model Context Protocol (MCP) server that exposes Kubb code generation as a tool for AI assistants. Once running, configure your AI client (Claude, Cursor, Windsurf, etc.) to connect — the assistant can then call kubb generate directly without leaving the chat.

Runs over stdio, which is compatible with local MCP clients such as Claude Desktop and Cursor.

npx kubb mcp

MCP client configuration

Add the following to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "kubb": {
      "command": "npx",
      "args": ["kubb", "mcp"]
    }
  }
}

Supporting Kubb

Kubb is an open source project, and its development is funded entirely by sponsors. If you would like to become a sponsor, please consider:

• Become a Sponsor on GitHub
• See sponsorship tiers and our sponsors

License

MIT