generate-client

Point the command at a description and give it an output path:

redocly generate-client openapi.yaml --output src/client.ts

That writes one self-contained file with a typed function for each operation:

import { listOrders, createOrder, configure } from './client.js';

configure({ auth: { bearer: process.env.API_TOKEN } });

const orders = await listOrders({ query: { status: 'open', limit: 10 } });
const created = await createOrder({ body: { items: [{ menuItemId: 'itm_1', quantity: 2 }] } });

The client has no dependencies, and it carries the behavior an API needs: auth for every scheme the description declares, opt-in retries, timeouts, middleware, pagination iterators, and typed server-sent events. Add a flag for each extra artifact you want:

redocly generate-client openapi.yaml -o src/client.ts \
  --generator zod --generator tanstack-query --generator mock --docs

The rest of this page describes the flags. Use the generated client describes what the output does.

The generate-client command generates API clients from an OpenAPI description:

• A typed TypeScript client (the default).
• Add-on modules for the TypeScript client, for example Zod schemas, TanStack Query factories, and MSW mocks.
• A command-line interface.
• SDKs for Python, Go, PHP, and Java.

For the full list, see Generators.

The TypeScript client has no dependencies. It uses only web-standard APIs (fetch, AbortController, URLSearchParams), so it runs in browsers, Node, Bun, Deno, and edge runtimes.

To use the generated code (auth, errors, middleware, retries), see Use the generated client.

redocly generate-client
redocly generate-client <api>
redocly generate-client <api> [--output=<path>] [--output-mode=<mode>] [--runtime=<mode>]
redocly generate-client <api> [--generator=<name>] [--args-style=<style>] [--error-mode=<mode>]
redocly generate-client <api> [--config=<path>]
redocly generate-client [--help]

You do not have to pass flags each time. Keep the settings in redocly.yaml under a top-level client block and per-API apis.<name>.client / clientOutput. See the client configuration reference for the fields. CLI flags take precedence over the configuration. Auto-pagination has no CLI flag. Declare it only as the client.pagination configuration or the x-redoclyPagination operation extension.

client:
  generators:
    - typescript
apis:
  cafe:
    root: ./openapi.yaml
    clientOutput: ./src/api/client.ts

redocly generate-client            # every api with a `client` block or `clientOutput`
redocly generate-client cafe       # just the `cafe` api

An unmatched path or URL uses the top-level client defaults. The --output flag names the entry file:

redocly generate-client openapi.yaml --output dist/client.ts

The --output-mode flag controls how the command splits the client into files:

• single (default): the command writes one file. The file is self-contained with the default inline runtime.
• split: the command writes two files. It puts the schema types and the type guards in a sibling file, <name>.schemas.ts. The entry file re-exports them. Because of this, your imports are the same as in single.

redocly generate-client openapi.yaml -o src/api/client.ts --output-mode split

The --runtime flag controls where the client engine lives:

• inline (default): the engine is embedded in the generated file, so the client is one self-contained file.
• module: the command writes the engine as real files in a runtime/ folder beside the client, and the client imports them relatively. Several generated clients in one repository can share one runtime/ folder, and you can read the engine as ordinary source files. The files are still machine-owned: the command regenerates them on every run.

Every generator that embeds an engine supports both modes, each in its language's shape:

• typescript and cli write runtime/*.ts modules.
• python writes the _*.py runtime modules beside the client, which imports them.
• go writes a runtime.go file in the same package as the client.
• php writes a runtime.php file that the client loads with require_once.
• java writes a <Class>Runtime.java base class that the client extends.

redocly generate-client openapi.yaml -o src/api/client.ts --runtime module

Set telemetry: on in the client block of your redocly.yaml file:

client:
  telemetry: on

The typescript, go, python, and php generators then also write a telemetry module next to the client:

The module counts the calls of your SDK per operation in windows of 60 seconds, and sends the counts at the end of each window. Use it to learn which operations your SDK users call, how often, with which outcome, and how fast. Without telemetry: on, the generated code contains no telemetry, and the client file is the same in both cases. This option is available only in the configuration file and has no flag.

Register the module once, where your SDK creates its client. The module counts each call once, after the last retry.

import { telemetry } from './client.telemetry.ts';
import { use } from './client.ts';

use(
  telemetry({ sdkName: '@acme/billing-sdk', sdkVersion: '3.2.0', client: 'invoice-worker/1.8.4' })
);

By default, the events go to the Redocly OpenTelemetry endpoint. Set endpoint to send them to another OTLP/HTTP traces URL, for example a local collector. Pass a sink function to receive the events yourself instead. Each event is a CloudEvent of type com.redocly.sdkUsage.aggregated. Its data holds two items: the operation with its counts, then the SDK.

If the connection fails or the endpoint answers 408, 429, or 5xx, the module adds the counts to the next window. After a timeout or any other failed send, it drops the counts.

Each event contains only:

• The operation ID.
• The number of calls and attempts, and the sum of their durations.
• The calls per outcome (2xx, 3xx, 4xx, 5xx, network_error, timeout, aborted) and the calls per duration bucket. An outcome or a bucket with no calls is not sent.
• The window start and length.
• The SDK name and version, the generator version, the language, and the runtime name and version, for example Node.js or CPython.
• The client name that you pass.

The module never sends URLs, path or query parameters, headers, request or response bodies, or any other value from a request.

To turn off sending at run time, set REDOCLY_SDK_TELEMETRY=off or DO_NOT_TRACK=1. Under PHP-FPM, the default clear_env = yes hides the host environment from PHP, so set the variable in the pool configuration, for example env[REDOCLY_SDK_TELEMETRY] = off. In a browser, the TypeScript module does nothing.

Use --report to write a JSON file that a script or a build tool can read:

redocly generate-client openapi.yaml -o src/api/client.ts --report generate-client-report.json

The command writes the file when the run succeeds. It has one entry for each API:

{
  "apis": [
    {
      "name": "cafe",
      "operations": [{ "id": "listMenuItems", "name": "listMenuItems" }],
      "findings": [
        {
          "kind": "name-changed",
          "message": "schema \"Error\" is a name a generated client already declares, so it is emitted as \"Error_2\" — ...",
          "operations": []
        }
      ]
    }
  ]
}

• operations lists every operation of the API. id is the operationId, or the generated name when the operation has none. It is the same ID that the usage telemetry sends. Two operations with the same operationId have the same id. name is the name in the generated TypeScript code. The other generators derive their names from it.
• findings lists the warnings of the run. A tool can act on kind, which does not change between releases. The message text can change. The operations of a finding are the IDs of the operations it is about. The list is empty when the finding is about the whole API, a schema, or a security scheme.
• When the run fails, the command exits with a code other than 0 and does not write the report. A file from an earlier run stays as it was, so check the exit code before you read the report.

• Use the generated client - Learn how to use the client produced by the generate-client command
• Move an app to a generated client - Replace a hand-written client, one call site at a time
• client configuration - Explore the settings for the generate-client command
• Lint command - Validate your API description before you generate a client
• Bundle command - Combine a multi-file description into one input file