cli_reference

CLI Reference

Usage

openapigen.exe --config <path/to/config.json>
openapigen.exe --init <folder> [--force]
openapigen.exe --help

openapigen runs entirely from a config file. There is no direct-arguments mode — the spec path, prefix and every output location live in config.json, so a run is reproducible and reviewable.

---

--config / -c

Run from a config file.

openapigen.exe --config ./myapi/config.json

The config specifies the input spec, the output root, the prefix, and where each generated file goes. On every run the tool also refreshes openapigen.schema.json beside the config and patches the config's $schema key, so an editor can offer completion and validation.

See Getting Started for the full config format.

---

--init / -i

Bootstrap a config.json and openapigen.schema.json in the given folder.

openapigen.exe --init ./myapi

Creates:

• ./myapi/config.json — default config pointing at ./openapi.json
• ./myapi/openapigen.schema.json — JSON schema for editor autocomplete

Edit config.json to point "input" at your spec, then run with --config.

--init will not overwrite an existing config.json. It refuses and exits 98:

'config.json' already exists in C:\path\to\myapi. Re-run with --force to overwrite it.

The schema file beside it is generated output with nothing to lose, so it is refreshed either way — re-running --init is the way to pick up a schema change after upgrading the tool.

Note: -i is --init, matching extgen. It is not --input; that mode was removed.

---

--force / -f

Only meaningful with --init. Overwrites an existing config.json instead of refusing.

openapigen.exe --init ./myapi --force

---

--help / -h

Print usage and exit.

---

Input formats

Both JSON and YAML are supported. The format is chosen from the file extension (.yaml / .yml → YAML; anything else → JSON).

URLs are not supported — input must be a local file path, resolved relative to the config file.

---

Config paths

Every outputFile resolves against root, and root resolves against the config file's own directory. Three rules apply to the resolved paths:

Two enabled outputs may not resolve to the same file. This is an error (exit 5) and nothing is written:

Outputs 'code.schemas' and 'code.helpers' both resolve to 'C:\...\same.gml'.
Each output needs its own file - one would silently overwrite the other.

Emitters run in a fixed order, so a shared destination would mean one output silently replacing another depending on an internal detail.

An output resolving outside root is a warning, not an error. It can be deliberate — pointing root at a .yyp while sending documentation to a sibling folder is a reasonable layout — so generation continues:

[openapigen] warning: output 'code.helpers' resolves outside 'root': C:\...\ESCAPED.gml

~ is only the home directory at the start of a path. ~/api/out.gml expands; a tilde anywhere else is an ordinary filename character, so my~helpers.gml is written literally.

Comments (//) and trailing commas are accepted in config.json. Note that patching the $schema key rewrites the file, and comments do not survive that rewrite.

---

Validation

Before generating, the parsed spec is checked by a set of rules. Every diagnostic is reported; any error stops the run.

Code	Severity	Meaning
IR_OP_001	Error¹	An operation has no operationId
IR_PATH_001	Error	A path parameter is not present in its path template
IR_SYM_001	Error¹	Two operations ask for the same GML function name
IR_SYM_002	Error²	Two schemas share a name

¹ Downgraded to a warning when "requireOperationId": false. ² Unreachable by construction — see below.

Generated function names are permanent public API, and operationId is the only stable, author-controlled source for them — a path-derived name changes whenever the URL is refactored, silently breaking callers, and derived names collide. Set "requireOperationId": false only for a third-party spec you cannot edit.

IR_SYM_001 — colliding function names

When two operations produce the same name, the generator appends a numeric suffix so the emitted file still compiles, and then reports what it had to do:

error IR_SYM_001: 2 operations generate the same function name 'create_user':
POST /user (kept 'create_user'), GET /thing (renamed to 'create_user_2').
Generated names are permanent public API and the suffix is positional - reordering
the spec would move it to a different operation. Give each a distinct operationId.

The suffix is positional: reordering the spec would move _2 to a different operation, silently changing which function a caller is bound to. Fix the spec rather than relying on it.

With "requireOperationId": false this drops to a warning and generation continues, because that mode exists for specs you are not able to edit.

IR_SYM_002 — duplicate schema names

Cannot currently fire, and is kept as an assertion. Component names are unique because OpenAPI keys them by name; two inline schemas are separated by a counter; and an inline schema can no longer take a component's name, because the generator reserves the whole component namespace before it builds anything.

Problems in the spec that do not prevent generation (a response missing its required description, for example) are reported as warnings and the run continues.

---

Exit codes

Code	Meaning
0	Success
1	Bad / missing arguments
2	Option parse error
3	Config file not found
5	Config JSON error, path resolution failure, colliding output paths, or schema patch failure
6	OpenAPI spec parse or validation error
30	Emitter failure
98	--init failure, or refusal to overwrite an existing config
99	Unhandled exception

---

Examples

# Bootstrap a config, then run it
openapigen.exe --init ./myapi
openapigen.exe --config ./myapi/config.json

# Regenerate after editing the spec
openapigen.exe --config ./myapi/config.json

# Re-scaffold a config from scratch, discarding the current one
openapigen.exe --init ./myapi --force