@kubb/cli

Generate files based on a kubb.config.ts configuration file using the Kubb CLI. The CLI displays progress updates including plugin execution status, file counts, and timing information during generation.

React-DevTools

Installation

bunpnpmnpmyarn

shell

bun add -d @kubb/cli

shell

pnpm add -D @kubb/cli

shell

npm install --save-dev @kubb/cli

shell

yarn add -D @kubb/cli

Usage

node

shell

kubb --config kubb.config.ts

mdx

USAGE kubb generate

COMMANDS
  init        Initialize a new Kubb project with interactive setup
  generate    [input] Generate files based on a 'kubb.config.ts' file
  validate    Validate a Swagger/OpenAPI file
  agent       Manage the Agent server
  mcp         Start the server to enable the MCP client to interact with the LLM.

Use kubb <command> --help for more information about a command.

`kubb init`

Initialize a new Kubb project with an interactive setup wizard. This command helps you quickly scaffold a Kubb project by:

Creating a package.json if one doesn't exist
Detecting your package manager (npm, pnpm, yarn, or bun)
Prompting for your OpenAPI specification path
Asking for the output directory
Letting you select which Kubb plugins to use
Installing the selected packages
Generating a kubb.config.ts file with your configuration

TIP

This is the recommended way to start a new Kubb project!

Usage

node

shell

npx kubb init

The interactive wizard will guide you through the setup process:

mdx

┌  Kubb Init
│
◇  Where is your OpenAPI specification located?
│  ./openapi.yaml
│
◇  Where should the generated files be output?
│  ./src/gen
│
◆  Select plugins to use:
│  ◼ OpenAPI Parser (Required)
│  ◼ TypeScript (Recommended)
│  ◻ Client (Fetch/Axios)
│  ◻ React Query / TanStack Query
│  ◻ Zod Schemas
│  └ More...
│
◇  Installing packages with pnpm...
│
◇  Creating kubb.config.ts...
│
└  ✓ All set!

Next steps:
  1. Make sure your OpenAPI spec is at: ./openapi.yaml
  2. Generate code with: npx kubb generate
     Or start a stream server with: npx kubb start
  3. Find generated files in: ./src/gen

NOTE

The init command automatically selects @kubb/plugin-oas and @kubb/plugin-ts as recommended defaults.

`kubb generate`

Generate files based on a kubb.config.ts file

TIP

kubb generate and kubb will call the same generate functionality.

mdx

USAGE kubb generate [OPTIONS]

OPTIONS

                        -c, --config    Path to the Kubb config
  -l, --logLevel=<silent|info|verbose|debug>    Log level control
                         -w, --watch    Watch mode based on the input file
                         -v, --verbose  Override logLevel to verbose (shows plugin timings)
                         -s, --silent   Override logLevel to silent (shows plugin timings)
                         -d, --debug    Override logLevel to debug (shows all details)
                          -h, --help    Show help

Path of the input file(overrides the one in kubb.config.js)

node

shell

kubb petStore.yaml

Options

--config (-c)

Path to the Kubb config.

node

shell

kubb --config kubb.config.ts

--log-level (-l)

silent: suppresses all log messages, warnings, and errors
info: logs warnings, errors, and informational messages (default)
verbose: adds plugin timing breakdown and performance metrics
debug: shows all messages from verbose plus detailed execution traces

node

shell

kubb --log-level verbose

--verbose (-v)

Enables verbose logging with plugin performance metrics. The summary shows plugin execution times and performance breakdown.

Output includes:

Plugin timing breakdown with visual bars
Performance metrics for slowest plugins
All info-level messages

node

shell

kubb --verbose

--debug

TIP

Debug mode creates detailed log files in the .kubb directory:

.kubb/kubb-{name}-{timestamp}.log - Contains all debug messages with timestamps

After each generation completes, the CLI will display the exact location of the debug log file.

Debug mode provides comprehensive logging including:

Setup phase details (configuration, plugins, paths)
Plugin installation and execution timing
Hook execution with duration measurements
Schema parsing information
File generation progress with paths
Formatter/linter execution details
Error messages with full stack traces

Use debug mode for:

Troubleshooting generation issues
Understanding plugin execution flow
Performance analysis
Debugging schema parsing problems

Alias for kubb generate --log-level debug

node

shell

kubb --debug

See the Debugging Guide for more details on using debug mode.

--watch (-w)

Watch mode based on the input file.

node

shell

kubb --watch

--version (-v)

Output the version number.

node

shell

kubb --version

--help (-h)

Display the help.

node

shell

kubb --help

`kubb start`

Start an HTTP server with SSE (Server-Sent Events) streaming for real-time code generation based on a kubb.config.ts file.

This command launches an HTTP server that provides:

Real-time progress updates via Server-Sent Events
RESTful API endpoints for configuration and health checks

mdx

USAGE kubb start [OPTIONS]

OPTIONS

                        -c, --config    Path to the Kubb config
  -l, --logLevel=<silent|info|verbose|debug>    Log level control
                         -v, --verbose  Override logLevel to verbose
                         -s, --silent   Override logLevel to silent
                         -d, --debug    Override logLevel to debug
                         -p, --port     Port for stream server
                         --host         Host for stream server
                          -h, --help    Show help

Path of the input file (overrides the one in kubb.config.js)

node

shell

kubb start petStore.yaml

Options

--config (-c)

Path to the Kubb config.

node

shell

kubb start --config kubb.config.ts

--log-level (-l)

Control logging verbosity:

silent: suppresses all log messages
info: logs warnings, errors, and informational messages (default)
verbose: adds plugin timing breakdown
debug: shows detailed execution traces

node

shell

kubb start --log-level debug

--port (-p)

Specify the port for the stream server. If not provided, an available port is automatically selected.

node

shell

kubb start --port 3000

--host

Specify the host for the stream server. Default: localhost

node

shell

kubb start --host 0.0.0.0 --port 3000

See the Stream Server Guide for complete documentation.

`kubb agent`

Start and manage the Kubb Agent Server, a HTTP server for code generation with WebSocket integration for real-time Studio communication.

IMPORTANT

@kubb/agent should be installed to use this command.

mdx

USAGE kubb agent [COMMAND] [OPTIONS]

COMMANDS
  start    Start the Agent server

Use kubb agent <command> --help for more information about a command.

`kubb agent start`

Start the Agent server with your Kubb configuration.

mdx

USAGE kubb agent start [OPTIONS]

OPTIONS

                        -c, --config    Path to the Kubb config (default: kubb.config.ts)
                         -p, --port     Port for the server (default: 3000)
                         --host         Host for the server (default: localhost)
                         --allow-write  Allow writing generated files to the filesystem
                         --allow-all    Grant all permissions (implies --allow-write)
                          -h, --help    Show help

Basic Usage

node

shell

kubb agent start

With custom config path:

node

shell

kubb agent start --config ./my-config.ts

With custom host and port:

node

shell

kubb agent start --host 0.0.0.0 --port 8080

Allow filesystem writes:

node

shell

kubb agent start --allow-write

Grant all permissions (implies --allow-write):

node

shell

kubb agent start --allow-all

Environment Setup

The agent automatically loads environment variables from:

.env - Base environment variables
.env.local - Local overrides (for secrets/local config)

Create a .env file in your project:

env

PORT=4000
KUBB_ROOT=./
KUBB_CONFIG=./kubb.config.ts
KUBB_AGENT_TOKEN=your_agent_token # this token should be created in the Kubb Studio interface, without you cannot interact
KUBB_STUDIO_URL=https://studio.kubb.dev
KUBB_ALLOW_WRITE=true
KUBB_ALLOW_ALL=false

Features

✅ Automatic config loading from environment variable (KUBB_CONFIG)
✅ Bidirectional WebSocket communication with Kubb Studio
✅ Use of Kubb generate behind the scenes

API Endpoints

Once the server is running, you can interact with it via HTTP:

`GET /api/health`

Check server health status.

bash

curl http://localhost:4000/api/health

`kubb validate`

Check syntax and structural errors in Swagger/OpenAPI files. The command provides feedback as errors or warnings.

Use in CI pipelines, pre-commit hooks, and development for early error detection.

IMPORTANT

@kubb/oas should be installed

TIP

The validation uses oas-normalize to validate Swagger/OpenAPI files.

mdx

USAGE kubb validate [OPTIONS]

OPTIONS

  -i, --input    Path to Swagger/OpenAPI file
   -h, --help    Show help

Options

--input (-i)

Path to the Swagger/OpenAPI file.

node

shell

kubb validate --input petstore.yaml

`kubb mcp`

Start a Model Context Protocol (MCP) server that exposes Kubb's code generation to AI assistants like Claude, Cursor, and other MCP-compatible tools.

The MCP server allows AI assistants to generate code from OpenAPI specifications using conversational commands.

IMPORTANT

@kubb/mcp should be installed to use this command.

bunpnpmnpmyarn

shell

bun add -d @kubb/mcp

shell

pnpm add -D @kubb/mcp

shell

npm install --save-dev @kubb/mcp

shell

yarn add -D @kubb/mcp

Usage

node

shell

npx kubb mcp

This starts an MCP server that communicates via stdio (standard input/output). MCP clients like Claude Desktop and Cursor can connect to this server.

For more information about configuring MCP for Kubb, see using Kubb MCP.

Telemetry

The Kubb CLI collects anonymous usage data after each kubb generate run to help improve the tool. No OpenAPI specs, file paths, plugin options, or secrets are ever collected.

Disable telemetry at any time:

shell

# Standard cross-tool opt-out (https://consoledonottrack.com)
DO_NOT_TRACK=1 kubb generate

# Kubb-specific opt-out
KUBB_DISABLE_TELEMETRY=1 kubb generate

See the Telemetry documentation for full details on what data is collected and how to opt out permanently.

@kubb/cli ​

Installation ​

Usage ​

kubb init ​

Usage ​

kubb generate ​

Options ​

--config (-c) ​

--log-level (-l) ​

--verbose (-v) ​

--debug ​

--watch (-w) ​

--version (-v) ​

--help (-h) ​

kubb start ​

Options ​

--config (-c) ​

--log-level (-l) ​

--port (-p) ​

--host ​

kubb agent ​

kubb agent start ​

Basic Usage ​

Environment Setup ​

Features ​

API Endpoints ​

GET /api/health ​

kubb validate ​

Options ​

--input (-i) ​

kubb mcp ​

Usage ​

Telemetry ​

@kubb/cli

Installation

Usage

`kubb init`

Usage

`kubb generate`

Options

--config (-c)

--log-level (-l)

--verbose (-v)

--debug

--watch (-w)

--version (-v)

--help (-h)

`kubb start`

Options

--config (-c)

--log-level (-l)

--port (-p)

--host

`kubb agent`

`kubb agent start`

Basic Usage

Environment Setup

Features

API Endpoints

`GET /api/health`

`kubb validate`

Options

--input (-i)

`kubb mcp`

Usage

Telemetry