# `generate-client`

Experimental
`generate-client` is an experimental feature: its flags, generated output, configuration schema, and custom-generator API may change in any minor release until it's stable.
We'd love your feedback while we stabilize it.

## Introduction

The `generate-client` command generates a typed TypeScript client from an OpenAPI 3.x description.
Swagger 2.0 descriptions are also accepted and normalized to the 3.x shape before generation.
The description is validated first: unresolved `$ref`s or structural errors fail generation with the problems listed, independent of your lint configuration.

The generated client has zero runtime dependencies by default — it uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`), so it runs in browsers, Node, Bun, Deno, and edge runtimes.
By default it emits a single self-contained file with inline types and one async function per operation.

The `<api>` argument is a file path, a URL, or an [`apis:` alias](/docs/cli/configuration), resolved the same way as in other commands such as `bundle` and `lint`.
An alias, or a path matching an api's `root`, uses that api's `client` block and `clientOutput`; an unmatched path or URL uses the top-level `client` defaults.
With no argument, a client is generated for every api that declares a `client` block or a `clientOutput` (see [`client` configuration](/docs/cli/configuration/reference/client)).

This page covers running the command; for the generated client's runtime API (auth, error handling, middleware, retries, and the add-on generators), see [Use the generated client](/docs/cli/guides/use-generated-client).

## Usage

```bash
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] [--version]
```

## Options

| Option | Type | Description |
|  --- | --- | --- |
| `api` | string | OpenAPI description file path, URL, or an `apis:` alias. Omit it to generate for every api that has a `client` block or `clientOutput`. |
| `--output`, `-o` | string | Output path (must end in `.ts`); the entry file in multi-file modes. Defaults to the api's `clientOutput`, else `<name>.client.ts` next to the configuration file. Single-API invocations only. |
| `--output-mode` | string | File layout. See [Choose an output mode](#choose-an-output-mode).  **Possible values:** `single`, `split`. Default value is `single`. |
| `--runtime` | string | Where the client's engine lives. See [Choose a runtime](#choose-a-runtime).  **Possible values:** `inline`, `package`. Default value is `inline`. |
| `--import-ext` | string | Extension in generated relative imports. See [Run with Node directly](/docs/cli/guides/use-generated-client#run-with-node-directly).  **Possible values:** `js` (the tsc/bundler convention), `ts` (for Node's built-in type stripping). Default value is `js`. |
| `--generator` | [string] | Generator to run — a built-in name (`tanstack-query` also has `-vue`/`-svelte`/`-solid` variants) or a custom generator's path or package; repeat the flag to run several. Default value is `sdk`. See [Generators](/docs/cli/guides/use-generated-client#generators). |
| `--args-style` | string | How operation inputs are passed. See [Argument style](/docs/cli/guides/use-generated-client#argument-style).  **Possible values:** `flat`, `grouped`. Default value is `flat`. |
| `--error-mode` | string | How operations report HTTP errors. See [Error handling](/docs/cli/guides/use-generated-client#error-handling).  **Possible values:** `throw`, `result`. Default value is `throw`. |
| `--date-type` | string | Type of `date`/`date-time` fields; pair `Date` with the `transformers` generator.  **Possible values:** `string`, `Date`. Default value is `string`. |
| `--mock-data` | string | Data mode for the `mock` generator.  **Possible values:** `static` (deterministic literals), `faker` (`@faker-js/faker` calls). Default value is `static`. |
| `--mock-seed` | number | Seed for `faker`-mode mocks, for reproducible data. Ignored in `static` mode. |
| `--server-url` | string | Override the server URL included in the client as its default. Accepts an absolute (`https://api.example.com`) or relative (`/v1`) URL. Defaults to `servers[0].url`. The app can also repoint the client at runtime — `createClient({ serverUrl })` or `configure({ serverUrl })`, see [Authentication](/docs/cli/guides/use-generated-client#authentication) in the usage guide. |
| `--setup` | string | Path to a publisher setup module that gets included in the client — pre-configure defaults such as the server URL, retries, headers, and middleware, so a published SDK ships with them built in. See [Publisher defaults](/docs/cli/guides/customize-client-generation#publisher-defaults). |
| `--config` | string | Specify path to the [configuration file](#generate-from-the-configuration-file). |
| `--help` | boolean | Show help. |
| `--version` | boolean | Show version number. |


## Examples

### Generate from the configuration file

Instead of passing flags every 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](/docs/cli/configuration/reference/client) for the fields.
CLI flags take precedence over the configuration.
Auto-pagination has no CLI flag; it's declared only as [`client.pagination`](/docs/cli/configuration/reference/client#pagination-object) configuration or the `x-redocly-pagination` operation extension.

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

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

### Generate from a file path or URL

An unmatched path or URL uses the top-level `client` defaults; `--output` names the entry file:

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

### Choose an output mode

`--output-mode` controls how the client is split across files:

- `single` (default) — one file (self-contained with the default `inline` runtime).
- `split` — two files: the schema types and type guards move to a sibling `<name>.schemas.ts`, and the entry file re-exports them, so your imports are the same as in `single`.


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

Both modes work with both runtimes.

### Choose a runtime

`--runtime` controls where the client's engine (request building, auth, retries, middleware, SSE) lives:

- `inline` (default) — the runtime source is embedded in the generated output (only the parts your API needs): self-contained, zero runtime dependencies.
- `package` — the generated file imports the runtime from `@redocly/client-generator` and contains only the types, operation descriptors, and thin call wrappers.


Choose `package` when you want engine fixes to arrive via `npm update @redocly/client-generator` with no regeneration; the consuming app must then have that package installed as a regular dependency.
Your application code is identical in both modes.
See [Package runtime](/docs/cli/guides/use-generated-client#package-runtime) in the usage guide and the [`package-runtime` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/package-runtime).

## Resources

- [Use the generated client](/docs/cli/guides/use-generated-client) — the runtime API and the add-on generators.
- [`client` configuration](/docs/cli/configuration/reference/client) — the `redocly.yaml` `client` block.
- [Lint command](/docs/cli/commands/lint) to validate your API description before generating a client.
- [Bundle command](/docs/cli/commands/bundle) to combine a multi-file description into a single input file.