Command-line reference

Every generator installs one command: openapi-to-typescript, openapi-to-zod, openapi-to-zod-playwright or openapi-to-k6. This page lists what the four commands accept, what init asks, what a run prints, which exit code it ends with and what runs without a licence key. It is for anyone wiring a generator into a script, a package.json task or a CI step.

The four commands side by side

All four commands share the same shape: run without arguments to generate from a configuration file, or run init to create one. Only openapi-to-k6 has a second way of running, direct mode, in which the spec and the output paths are passed as flags.

Command	Package	Config file it looks for	Modes	Default execution mode
openapi-to-typescript	@spartaficial/openapi-to-typescript	openapi-to-typescript.config.ts, .json, package.json key	config, init	parallel
openapi-to-zod	@spartaficial/openapi-to-zod	openapi-to-zod.config.ts, .json, package.json key	config, init	parallel
openapi-to-zod-playwright	@spartaficial/openapi-to-zod-playwright	openapi-to-zod-playwright.config.ts, .json, package.json key	config, init	sequential
openapi-to-k6	@spartaficial/openapi-to-k6	openapi-to-k6.config.ts, .json, package.json key	config, direct mode, init	parallel

The Playwright generator runs its specs one at a time by default because each spec writes several files that import each other; set executionMode: "parallel" in the config file to change that. The configuration file format itself is described in Configuration files.

Common options

The three options every command accepts:

Option	Meaning
-c, --config <path>	Read this configuration file instead of searching for one. The path may be .ts or .json.
-V, --version	Print the package version and exit with code 0.
-h, --help	Print the usage text, including the command's examples, and exit with code 0.

Running --help shows the full option list of that command. For openapi-to-zod it is:

Usage: openapi-to-zod [options] [command]

Generate Zod v4 schemas from OpenAPI specifications

Options:
  -V, --version        output the version number
  -c, --config <path>  Path to config file (openapi-to-zod.config.{ts,json})
  -h, --help           display help for command

Commands:
  init                 Initialize a new openapi-to-zod configuration file

Config mode (the default)

Running a command with no subcommand generates from a configuration file. This is the mode to use in scripts.

npx openapi-to-zod
npx openapi-to-zod --config config/openapi-to-zod.config.ts

Without --config, the command searches upwards from the current directory for <command>.config.ts, then <command>.config.json, then a package.json with a <command> key. A .ts config is transpiled on the fly and may import from the project it lives in; a .json config needs nothing installed. When no file is found the command stops with:

No config file found. Searched for: openapi-to-zod.config.ts, openapi-to-zod.config.json, package.json (openapi-to-zod key)
Run 'openapi-to-zod init' to create a new config file.

A run then proceeds in a fixed order:

1. The configuration is loaded and validated against the generator's option schema. An unknown key, a missing output path or a value outside the allowed set stops the run before anything is written; the messages are listed in Troubleshooting.
2. The licence is checked and a one-line summary is printed; see Licensing.
3. The defaults block is merged into every entry of specs, and the specs are handed to the batch executor, in parallel (ten at a time unless batchSize says otherwise) or sequentially.
4. Each spec is generated. A spec that fails does not stop the others.
5. A summary is printed and the process exits with the batch's exit code.

The progress output of a two-spec run looks like this:

Executing 2 specification(s) in parallel (batch size: 10)...

Processing [1/2] specs/api.yaml...
  ✓ Generated src/generated/schemas.ts
Processing [2/2] specs/api.yaml...
  ✓ Generated src/generated/types.ts
  ✓ Generated src/generated/schemas-split.ts

==================================================
Batch Execution Summary
==================================================
Total specs: 2
Successful: 2
Failed: 0
==================================================

A failed spec is reported inline and again in the summary, with the error message:

Processing [1/1] specs/empty.yaml...
✗ Failed to generate src/generated/schemas.ts: Empty or invalid OpenAPI specification in specs/empty.yaml

==================================================
Batch Execution Summary
==================================================
Total specs: 1
Successful: 0
Failed: 1

Failed specs:
  ✗ specs/empty.yaml
    Error: Empty or invalid OpenAPI specification in specs/empty.yaml
==================================================

openapi-to-k6 additionally prints a short greeting before generation and Generation complete! after it.

init

init writes a configuration file after a short interactive dialogue. It asks the same first questions for every generator, then the questions specific to the generator, and finally where to write the file.

npx openapi-to-zod init

The shared part of the dialogue:

1. If <command>.config.ts or <command>.config.json already exists in the current directory, init asks whether to overwrite it and stops when the answer is no.
2. It lists the .yaml, .yml and .json files it finds under spec/ and specs/ (the first twenty, alphabetically) and asks you to pick one, with an "Enter manually..." escape hatch. When neither folder exists it asks for the path directly, suggesting openapi.{yaml,yml,json} (openapi.yaml for k6). A path that does not exist yet is accepted after a warning.
3. It asks the generator's own questions, listed below.
4. It writes <command>.config.ts or <command>.config.json into the current directory and prints the next steps.

The generator-specific prompts and the config each one writes:

Generator	Prompts (default answer)	defaults block written when you accept "recommended defaults"
openapi-to-typescript	Output TypeScript file path (src/types.ts); Enum format (union, enum or const-object; the dialogue suggests union); Config file format (ts or json); Include commonly-used recommended defaults? (yes)	enumFormat, includeDescriptions: true, showStats: true
openapi-to-zod	Output TypeScript file path (src/schemas.ts); Config file format; Include recommended defaults? (yes)	mode: "strict", includeDescriptions: true, useDescribe: false, showStats: true, schemaType: "all"
openapi-to-zod-playwright	Output file path for schemas and types (tests/schemas.ts); Output file path for client class (tests/client.ts); Output file path for service class (empty to skip); Config file format; Include recommended defaults? (yes)	mode: "strict", includeDescriptions: true, useDescribe: false, showStats: true, validateServiceRequest: false
openapi-to-k6	Output file path for K6 client (k6/api-client.ts); Output file path for types (k6/api-types.ts); Use operationId for method names? (no); Configuration file format	Always written: includeDescriptions: true, showStats: true, preferredContentTypes: ["application/json"]

Two details worth knowing. The TypeScript dialogue suggests enumFormat: "union", but a config that leaves enumFormat out gets the generator's own default, const-object; the written file always states the value explicitly, so what you see is what you get. The k6 dialogue lets you leave the types path empty, but outputTypes is required by the k6 configuration schema, so keep the suggested path. The generated file is an ordinary config file; everything it contains is explained in Configuration files and the per-generator option references (TypeScript, Zod, Playwright, k6).

openapi-to-k6 direct mode

The k6 command can run without a configuration file. Direct mode is selected as soon as any of --input, --output or --output-types is given, and then all three are required.

npx openapi-to-k6 --input openapi.yaml --output k6/client.ts --output-types k6/types.ts
npx openapi-to-k6 --input openapi.yaml --output k6/client.ts --output-types k6/types.ts --output-service k6/service.ts

Flag	Config option it corresponds to	Meaning
-i, --input <path>	input	The OpenAPI specification file. Required.
-o, --output <path>	outputClient	Where the k6 client is written. Required.
-t, --output-types <path>	outputTypes	Where the TypeScript types are written. Required.
-s, --output-service <path>	outputService	Also write the service wrapper to this path.
--use-operation-id	useOperationId: true	Name methods after operationId instead of method and path.
--base-path <path>	basePath	Prefix every request URL with this path.
--no-descriptions	includeDescriptions: false	Leave JSDoc descriptions out of the generated files.
--no-stats	showStats: false	Do not print the path and operation counts.

Direct mode has no defaults, no operation filters and no refMappings; anything beyond these flags needs a configuration file. Once any direct-mode flag is present, --config is ignored: the two modes do not combine. Leaving one of the three required flags out stops the run with:

Direct mode requires --input, --output, and --output-types.

Direct mode is also the one case where the project a licence is bound to is taken from the current directory rather than from a config file's location; Licensing explains when that matters.

What a run prints

Beyond the progress lines, two options control extra output. Both default to true.

showStats adds generation statistics. The TypeScript, Zod and Playwright generators write them as a comment block at the top of each generated file, so they travel with the output:

// Generation Statistics:
//   Total schemas: 3
//   Circular references: 0
//   Discriminated unions: 0
//   With constraints: 0
//   Generated at: 2026-11-04T18:44:40.240Z

When operation filters are active the block also lists how many operations each filter removed. The k6 generator prints its counts to the terminal instead, under the file it just wrote:

  ✓ Generated types: k6/types.ts
  ✓ Generated K6 client: k6/client.ts
    Paths: 5, Operations: 8/8
  ✓ Generated K6 service: k6/service.ts
    Service methods: 8

showWarnings controls whether the generator reports things it noticed but did not stop for: a filter pattern that matched nothing, a $ref that could not be resolved, two schemas that normalise to the same name, a conditional it could not express. Warnings are collected during a spec and printed as one block on standard error when that spec finishes:

[@spartaficial/openapi-to-zod] Warnings:
  ⚠️  Name collision: "schema "Pet_Kind"" and "schema "pet-kind"" both generate "petKindSchema". The generated file will declare it twice - rename one, or use prefix/suffix to separate them.

Set showWarnings: false to silence the block; the output is unchanged either way. Both options are listed in each generator's option reference, for example Zod options.

Exit codes

Code	When
0	Every spec generated; --help; --version; init completed or was cancelled.
1	The configuration could not be found or failed validation; a direct-mode flag is missing; a module the config imports is not installed; the licence check failed; at least one spec failed; any other error.

The batch exit code is all-or-nothing: one failed spec out of ten exits 1, so a CI step cannot pass on partial output. An unknown option or a missing option argument is rejected by the command-line parser, also with exit code 1.

Error output and stack traces

Configuration errors, direct-mode option errors and a missing module in a .ts config print their message bare, because the message already says what to change. Anything else, such as a spec that cannot be parsed outside the batch or a write failure, prints as Error: <message>.

The TypeScript, Zod and Playwright commands always append the stack trace to such an unexpected error. The k6 command keeps the trace behind the DEBUG environment variable, so that a plain config mistake does not scroll a page:

DEBUG=1 npx openapi-to-k6

init never prints a stack trace.

What runs without a licence key

--help, --version and init run without a licence key; generating in config mode or direct mode requires SPARTAFICIAL_LICENSE_KEY to be set, and Licensing explains the key, where to set it and what each licence error means.