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 or OpenAPI 3.1 specification, in either YAML or JSON format.

When used in conjunction with --input-type typespec then a TypeSpec 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

--override-specification-title <value>

As environment variable OPENAPI_OVERRIDE_SPECIFICATION_TITLE

Allows overriding the info.title field of the input OpenAPI document. This field is used to generate some symbol names, and so this is useful when you don’t directly control the source specification, and wish to customize the output symbol names.

-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)

--ts-server-implementation-method (experimental) (server sdks only)

As environment variable OPENAPI_TS_SERVER_IMPLEMENTATION_METHOD

Determines whether to represent server stubs / interfaces as type, interface, or abstract class entities.

This is mostly a case of personal preference, but can be important for better integration with dependency injection frameworks, such as diod which rely on abstract class objects to define interfaces for injection.

Default: type

--filename-convention <value>

As environment variable OPENAPI_FILENAME_CONVENTION

Determines which naming convention to use for dynamically generated filenames (eg: those generated from tags or route prefixes).

Default: kebab-case

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, urls secured by an authenticating proxy like GCP IAP Proxy, 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” the headers would not be sent for requests to other ports, resource paths, or protocols, but a less specific uri like “https://example.com” 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