Kubb banner [![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![Stars][stars-src]][stars-href] [![License][license-src]][license-href] [![Node][node-src]][node-href]

Documentation · Report Bug · Request Feature


# @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)

My sponsors

## License [MIT](https://github.com/kubb-labs/kubb/blob/main/licenses/LICENSE-MIT) [npm-version-src]: https://shieldcn.dev/npm/v/@kubb/cli.svg?variant=secondary&size=xs&theme=zinc&mode=dark [npm-version-href]: https://npmx.dev/package/@kubb/cli [npm-downloads-src]: https://shieldcn.dev/npm/dm/@kubb/cli.svg?variant=secondary&size=xs&theme=zinc&mode=dark [npm-downloads-href]: https://npmx.dev/package/@kubb/cli [stars-src]: https://shieldcn.dev/github/stars/kubb-labs/kubb.svg?variant=secondary&size=xs&theme=zinc&mode=dark [stars-href]: https://github.com/kubb-labs/kubb [license-src]: https://shieldcn.dev/npm/license/@kubb/cli.svg?variant=secondary&size=xs&theme=zinc [license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE [node-src]: https://shieldcn.dev/npm/node/@kubb/cli.svg?variant=secondary&size=xs&theme=zinc&mode=dark [node-href]: https://npmx.dev/package/@kubb/cli