Skip to content
Commands

kubb generate

The generate command runs the Kubb code-generation pipeline from your kubb.config.ts, with watch mode, dry runs, and cli, json, file, and html reporters.

kubb generate turns your spec into code with the plugins in your kubb.config.ts. It is the default command: kubb alone runs it.

Terminal
kubb generate                  # input from the config
kubb generate ./petStore.yaml  # this spec instead

Arguments

ArgumentWhat it does
[input]Path, URL, or git input (git+<repo>#<ref>:<path>) of a Swagger or OpenAPI document. Overrides the config's input.

Options

FlagAliasDefaultWhat it does
--config <path>-cPath to a config file, such as ./kubb.staging.ts.
--log-level <level>-linfosilent, info, or verbose. verbose shows plugin timings.
--silent-sfalseSame as --log-level silent.
--verbosefalseSame as --log-level verbose.
--reporter <names>cliComma-separated reporters to run: cli, json, file, html.
--watch-wfalseGenerate again when the local input file changes.
--dry-runfalsePreview the run. Writes no files and skips formatting, linting, and output.postGenerate.

Watch mode

--watch watches only a local input file. A URL or git input generates once, so run Kubb again when the remote spec changes. In an interactive terminal, press r to rebuild and q to quit. See Watch mode details.

Reporters

A reporter decides how you see a run. The config's reporters registers all four by default, and --reporter picks which ones run.

ReporterOutput
cliThe end-of-run summary in the terminal. Plain text in non-interactive terminals and AI agent sessions.
jsonA machine-readable report on stdout for CI. The run log goes to stderr. See Machine-readable output for the shape.
fileThe summary, plugin timings, and problems in .kubb/kubb[-<name>]-<timestamp>.log. <name> is the config's name, if set.
htmlA browsable report of the generated files and diagnostics in .kubb/kubb[-<name>]-<timestamp>/index.html.
Terminal
kubb generate --reporter file       # write a log file
kubb generate --reporter json       # print a JSON report for CI
kubb generate --reporter cli,html   # run two reporters

The cli summary shows the outcome and duration, the plugin results, the output path, and the file changes:

Summary
✓ Generation complete  466ms

  17 files generated · 54 unchanged
  Plugins  4 passed
  Output   ./src/gen

File changes
  14 added · 3 modified · 1 deleted
  Lines  +312 −47

See Run summary.

Exit codes

CodeWhen
0The run succeeds.
1The config fails to load, or any config fails to generate. One failing config does not stop the others.

Less common cases

Watch mode details

With kubb generate --watch, Kubb watches only a local input file. A URL or git input generates once, so run Kubb again when the remote spec changes. Kubb does not watch the files the input references with $ref, such as schemas/Pet.yaml. After you edit one, press r or run Kubb again.

EventWhat happens
The first build failsKubb keeps watching, so you can fix the input.
A rebuild endsA line shows the duration and the schemas and operations the spec gained or lost. The summary below it lists the files the rebuild added, modified, or removed.
You press rKubb rebuilds. Keys work in an interactive terminal.
You press qKubb quits with exit code 0.
You press Ctrl+CKubb quits with exit code 130.

To keep clean off during incremental runs, pass a function to defineConfig and read watch. See Config function.

Adapter sources

When you write an adapter, its sources member lists the files and URLs the last parse() read, even unreadable ones. A watcher can rebuild when one of them changes, but kubb generate --watch does not read them. See Adapters.

Run summary

When a run ends, the cli reporter prints a summary. It starts with the outcome and duration, then the plugin results and the output path.

Summary
✓ Generation complete  466ms

  17 files generated · 54 unchanged
  Plugins  4 passed
  Output   ./src/gen

File changes
  14 added · 3 modified · 1 deleted
  Lines  +312 −47
EntryWhat it counts
unchangedFiles whose content did not change, also when output.clean rewrites the folder.
File changesThe output on disk compared with its content before the run. Custom storage drivers leave this section out.
LinesThe count of each line, so moving a line inside a file is not a removal plus an addition.

With --dry-run, the summary shows the planned file changes. It says "planned" and "Nothing was written."