CLI Configuration Reference

All CLI options can be provided as command-line parameters, or environment variables as you prefer.

Generate

The default action is to run code generation.

Required Parameters

-i --input <value>

As environment variable OPENAPI_INPUT

Path to the input specification to generate from. Either a local path, or a url may be provided, though not all specifications will build correctly from a url.

By default, this must be a OpenAPI 3.0 (opens in a new tab) or OpenAPI 3.1 (opens in a new tab) specification, in either YAML or JSON format.

When used in conjunction with --input-type typespec then a TypeSpec (opens in a new tab) specification can be supplied instead.

-o --output <value>

As environment variable OPENAPI_OUTPUT

directory to output generated code (env: )

-t --template <value>

As environment variable OPENAPI_TEMPLATE

Which template you wish to generate, one of:

• typescript-koa
• typescript-fetch
• typescript-axios
• typescript-angular

Optional Parameters

--input-type <value>

As environment variable OPENAPI_INPUT_TYPE

What type of input file is being provided, one of:

• openapi3 (default)
• typespec

-s --schema-builder <value>

As environment variable OPENAPI_SCHEMA_BUILDER

Which runtime schema parsing library to use, one of:

• zod (default)
• joi

--grouping-strategy <value> (experimental)

As environment variable OPENAPI_GROUPING_STRATEGY

Strategy to use for splitting output into separate files. Set to none for a single generated.ts file, one of:

• none don't split output, yield single generated.ts (default)
• first-tag group operations based on their first tag
• first-slug group operations based on their first route slug/segment

--enable-runtime-response-validation (experimental)

As environment variable OPENAPI_ENABLE_RUNTIME_RESPONSE_VALIDATION

Controls whether to validate response bodies using the chosen runtime schema library.

Default false

--enable-typed-base-paths (client sdks only)

As environment variable OPENAPI_ENABLE_TYPED_BASE_PATHS

Controls whether to generate a union-type of string literals + string from the openapi specifications array of server urls. Handy for intellisense.

Default: true

--extract-inline-schemas (experimental)

As environment variable OPENAPI_EXTRACT_INLINE_SCHEMAS

Generate names based on usage, and extract in-line schemas to be standalone types / schemas in the generated code. This is especially useful when dealing with input schemas that don't make good use of named $ref's.

Default false

--allow-unused-imports

As environment variable OPENAPI_ALLOW_UNUSED_IMPORTS

Allow unused imports to be emitted in generated code. Offered as an escape hatch if any bugs in the unused-import elimination occur.

Default false

--ts-allow-any

As environment variable OPENAPI_TS_ALLOW_ANY

Determines whether to use any or unknown when generating types for schemas that don't have concrete definitions. Eg: additionalProperties: true or {} schemas.

Using unknown will push you towards using type guards / making runtime checks before interacting with the model and should generally result in more robust code, whilst any may be more convenient during rapid prototyping.

Default: false (use unknown rather than any)

Misc

--remote-spec-request-headers (authenticated remote specifications)

As environment variable OPENAPI_REMOTE_SPEC_REQUEST_HEADERS

Allows providing request headers to use when fetching remote specifications. This allows for running generation against remote sources that require authentication.

Common examples include private github repositories (opens in a new tab), urls secured by an authenticating proxy like GCP IAP Proxy (opens in a new tab), or just generally authenticated servers

The format of the value is a JSON object keyed by URI, with values being either an object, or array of {name, value} pairs. As a typescript type:

type value = {
  [uri: string]: { name: string, value: string }[] | { name: string, value: string }
}

For example:

{
  "https://example.com": [
    {"name": "X-Client-Id", "value": "my-client-id"},
    {"name": "X-Client-Secret", "value": "some-secret-value"}
  ],
  "https://example.org/some/path": {"name": "Proxy-Authorization", "value": "some token"}
}

A full match on the provided uri is required for the headers to be sent. Eg: given a uri of "https://exmaple.com:8080/openapi.yaml (opens in a new tab)" the headers would not be sent for requests to other ports, resource paths, or protocols, but a less specific uri like "https://example.com (opens in a new tab)" will send headers on any (https) request to that domain.

jq --null-input --compact-output \
  --arg domain "https://example.com" \
  --arg name "authorization" \
  --arg value "secret value" '{$domain: {$name, $value}}'

node -p 'JSON.stringify({[process.argv[1]]: {name: process.argv[2], value: process.argv[3]}})' \
  https://example.com \
  authorization \
  'some secret value'

-h, --help

Displays help text for command