CLI
The codegen, init, and doctor commands.
npx nestjs-codegen <command>In dev, prefer NestjsCodegenModule.forRoot() —
it starts the codegen with your app, no separate process. The CLI is for CI: a
watch-free run that fails the build if the committed client has drifted before you deploy.
codegen
Discover controllers/pages and emit the generated files. Reads
nestjs-codegen.config.ts.
npx nestjs-codegen codegen # one-shot
npx nestjs-codegen codegen --watch # regenerate on file changesThe watcher debounces and holds a lock file so two watchers don't fight over the output directory.
init
Scaffold a starter nestjs-codegen.config.ts (and, for Inertia projects, the app
entry + page wiring).
npx nestjs-codegen initdoctor
Diagnose a project's setup — missing config, unscanned controllers, output drift — and print suggested fixes.
npx nestjs-codegen doctorEach check prints ✓ (pass) or ✗ (fail) with a one-line fix hint. Checks that can be
repaired automatically are marked (fixable with --fix).
doctor --fix
Re-run with --fix and doctor applies every auto-fixable repair in place instead of only
suggesting it — scaffolding a missing config, patching nest-cli.json assets, adding
tsconfig path aliases / excludes, creating the dedicated tsconfig.inertia.json,
appending .gitignore entries, installing missing packages with your detected package
manager, adding build:client / typecheck:inertia scripts, and more:
npx nestjs-codegen doctor --fixFixed checks print ⚡ … (fixed); anything still not repairable prints ✗ with its manual
hint. The summary reports how many issues were auto-fixed and how many remain. doctor
exits non-zero while any check is still failing, so it's safe to gate CI on it.
A handful of checks are intentionally not auto-fixable — e.g. vite.config.ts edits,
which are too project-specific to patch safely. Those always print a manual hint, with or
without --fix.
The TypeScript config (nestjs-codegen.config.ts) is loaded natively on modern Node
(>= 22.18 / 23.6 / 24 / 25), which strips TypeScript types on import — so no extra tooling
is needed, including on Node 25. On older Node without native type stripping the loader
falls back to tsx (an optional peer); install it if you see a config-loading error:
pnpm add -D tsx.