Commands

Command	What it does
run	Interactive setup — start here (English / Português)
add	Connect another API
generate	Generate everything — the default command (--prune, --watch)
diff	What would change, without writing
info	What your config resolves to: folders, env variables, counts
init	Write a commented starter config

Every command accepts --config <path>; by default openapi-gen.config.{mjs,js,ts,mts} is used. --version and --help work anywhere.

run

npx openapi-gen run
npx openapi-gen run --lang pt

The wizard asks a handful of questions, one step at a time:

1. Language — English or Português (defaults to your system language; skip it with --lang en|pt)
2. Framework — detected from your package.json and folders
3. Hooks library — React only
4. OpenAPI spec — loaded right away: you see the API name and number of endpoints, or a clear error such as "this is the Swagger UI page, use /api-json"
5. API name — suggested from the spec title
6. Backend URL — the env variable, and a fallback taken from the spec's servers
7. Authentication — the login cookie, or nothing

Choices are numbered — type 1, 2… or press Enter for the suggestion. Type ? at any question for an explanation of that step with examples.

Before writing anything it shows a review: the config file, what will be generated (routes, services, hooks and where), and the variables to put in your .env. You can save and generate, save only, or cancel. After generating, it offers to install the packages the generated code needs, and to connect another API.

If a config already exists, run offers to add an API to it or start over.

For scripts and CI, --yes accepts every suggestion:

npx openapi-gen run --yes --spec ./openapi.json

add

npx openapi-gen add

Asks for the spec, a name and the backend URL variable, shows the review and adds the API to your config — as text, so your comments and formatting are kept. The new API gets its own folders (src/app/api/<name>, src/services/<name>) and reuses the shared auth and helpers. Accepts --lang, --yes and --spec like run.

generate

npx openapi-gen generate
npx openapi-gen generate --prune
npx openapi-gen generate --watch

1. Validates the config — typos included: unknown option "framwork" — did you mean "framework"?
2. Loads every spec and applies include / exclude.
3. Plans every file. If two APIs would write the same file, it stops before writing anything.
4. Writes the helpers, routes, services (with an index.ts re-exporting them) and hooks.
5. Reports stale files — generated files whose endpoints left the spec. --prune deletes them. Only files starting with the Auto-generated by codegen-openapi header are ever touched.
6. Runs your afterGenerate commands (e.g. Prettier).
7. Checks packages and prints the install command for anything missing (npm, pnpm, yarn or bun).

--watch regenerates whenever the config or a local spec file changes; remote specs are checked every 10 seconds.

The command exits with code 1 on errors, so it can run in CI.

diff

npx openapi-gen diff

Shows, without writing, which files would be added and which generated files are no longer in the spec.

info

npx openapi-gen info

Explains what the config means once defaults are applied — useful when something ends up in an unexpected place:

[core] nextjs
  spec            https://api.example.com/api-json
  endpoints       42
  path prefix     /api (left out of file names, kept in backend calls)
  backend URL     API_URL  (fallback: https://api.example.com)
  routes          18 → src/app/api/
  services        6 → src/services/
  auth            cookie accessToken → Authorization: Bearer

.env
  API_URL=https://api.example.com

init

npx openapi-gen init

Writes a commented starter config using your project's folders, without asking anything. run is usually faster because it fills in the values for you.