# @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
```bash
bun add -D @kubb/cli
# or
pnpm add -D @kubb/cli
# or
npm install -D @kubb/cli
```
## Commands
- [`kubb init`](#kubb-init) — scaffold a new project
- [`kubb generate`](#kubb-generate) — run code generation
- [`kubb studio`](#kubb-studio) — connect this project to Kubb Studio
- [`kubb validate`](#kubb-validate) — validate an OpenAPI spec
- [`kubb mcp`](#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.
```bash
npx kubb init
```
#### Options
| Flag | Short | Type | Default | Description |
| ------------------ | ----- | ------- | ---------------- | ------------------------------------------ |
| `--yes` | `-y` | boolean | `false` | Skip all prompts and use defaults |
| `--input ` | `-i` | string | `./openapi.yaml` | Path to the OpenAPI specification |
| `--output ` | `-o` | string | `./src/gen` | Output directory for generated files |
| `--plugins ` | | 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
```bash
# 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.
```bash
npx kubb generate
```
#### Options
| Flag | Short | Type | Default | Description |
| --------------------- | ----- | ------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `[input]` | | string | | OpenAPI file path or URL that overrides `input` in the config |
| `--config ` | `-c` | string | | Path to the Kubb config file |
| `--log-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 ` | | string | `cli` | Reporters that render the run, comma-separated: `cli`, `json`, `file`, `html`. Overrides `config.reporters` |
#### Examples
```bash
# 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](https://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.
```bash
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 ` | `-c` | string | | Path to the Kubb config file |
| `--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-install` | | boolean | `false` | Let Studio install extensions with `kubb add`; needs `--allow-config-edit` too. Asked once |
| `--allow-update` | | boolean | `false` | Let Studio update installed extensions with `kubb update`. Asked once |
| `--allow-remove` | | boolean | `false` | Let Studio remove extensions with `kubb remove`; needs `--allow-config-edit` too. Asked once |
| `--allow-save-input` | | boolean | `false` | Let Studio save the spec it sends as `input`; needs `--allow-config-edit` too. Asked once |
| `--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 ` | `-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
```bash
# 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.
```bash
npx kubb validate
```
#### Arguments
| Argument | Required | Description |
| --------- | -------- | --------------------------------------------------- |
| `` | ✅ | Path or URL to the OpenAPI/Swagger file to validate |
#### Examples
```bash
# 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 with three tools for AI assistants: `generate`, `validate`, and `init`. Once your AI client connects, the assistant can validate a spec, scaffold a `kubb.config.ts`, and run generation without leaving the chat.
The server uses stdio, so the client starts it as a local process. It looks for `kubb.config.*` in the folder the client starts it in.
```bash
npx kubb mcp
```
#### MCP client configuration
In Claude Code, run this from your project root:
```bash
claude mcp add kubb -- npx kubb mcp
```
For other clients, add the following to your MCP client config, such as `claude_desktop_config.json` for Claude Desktop:
```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](https://github.com/sponsors/stijnvanhulle)
- [See sponsorship tiers and our sponsors](https://kubb.dev/sponsors)