kubb generate
kubb generate turns your spec into code with the plugins in your kubb.config.ts. It is the default command: kubb alone runs it.
kubb generate # input from the config
kubb generate ./petStore.yaml # this spec insteadArguments
| Argument | What it does |
|---|---|
[input] | Path, URL, or git input (git+<repo>#<ref>:<path>) of a Swagger or OpenAPI document. Overrides the config's input. |
Options
| Flag | Alias | Default | What it does |
|---|---|---|---|
--config <path> | -c | Path to a config file, such as ./kubb.staging.ts. | |
--log-level <level> | -l | info | silent, info, or verbose. verbose shows plugin timings. |
--silent | -s | false | Same as --log-level silent. |
--verbose | false | Same as --log-level verbose. | |
--reporter <names> | cli | Comma-separated reporters to run: cli, json, file, html. | |
--watch | -w | false | Generate again when the local input file changes. |
--dry-run | false | Preview 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.
| Reporter | Output |
|---|---|
cli | The end-of-run summary in the terminal. Plain text in non-interactive terminals and AI agent sessions. |
json | A machine-readable report on stdout for CI. The run log goes to stderr. See Machine-readable output for the shape. |
file | The summary, plugin timings, and problems in .kubb/kubb[-<name>]-<timestamp>.log. <name> is the config's name, if set. |
html | A browsable report of the generated files and diagnostics in .kubb/kubb[-<name>]-<timestamp>/index.html. |
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 reportersThe cli summary shows the outcome and duration, the plugin results, the output path, and the file changes:
✓ Generation complete 466ms
17 files generated · 54 unchanged
Plugins 4 passed
Output ./src/gen
File changes
14 added · 3 modified · 1 deleted
Lines +312 −47See Run summary.
Exit codes
| Code | When |
|---|---|
0 | The run succeeds. |
1 | The 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.
| Event | What happens |
|---|---|
| The first build fails | Kubb keeps watching, so you can fix the input. |
| A rebuild ends | A 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 r | Kubb rebuilds. Keys work in an interactive terminal. |
You press q | Kubb quits with exit code 0. |
| You press Ctrl+C | Kubb 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.
✓ 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| Entry | What it counts |
|---|---|
unchanged | Files whose content did not change, also when output.clean rewrites the folder. |
File changes | The output on disk compared with its content before the run. Custom storage drivers leave this section out. |
Lines | The 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."
