@redocly/client-generator 0.3.7 → 0.4.0

package/README.md

@@ -10,8 +10,8 @@ See https://github.com/Redocly/redocly-cli for the full project.
 
 The generated client uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`), so by default it is a single self-contained file with zero runtime dependencies that runs in browsers, Node ≥ 18, Bun, Deno, and edge runtimes.
 (Running the generator itself requires the Node version in this package's `engines` field.)
-Code is produced through the TypeScript compiler AST, not string templates; `typescript` is the only peer dependency — optional, needed only when you run generation, and it must be 6.x there (TypeScript 7's native compiler has no compiler API).
-Apps that only consume a package-runtime client don't need it at all, and can compile the generated code with any TypeScript, including 7.
+Code is printed through per-language text printers; `typescript` is the only peer dependency — optional, needed only when generation bakes a `--setup` module, and it must be 6.x there (TypeScript 7's native compiler has no compiler API).
+Apps that only consume a generated client don't need it at all, and can compile the generated code with any TypeScript, including 7.
 
 This package is the engine behind the [`generate-client` command](https://redocly.com/docs/cli/commands/generate-client) — install [`@redocly/cli`](https://www.npmjs.com/package/@redocly/cli) to run it from the command line or `redocly.yaml`.
 How to use the generated client — auth, middleware, retries, pagination, Server-Sent Events, and the add-on generators (`zod`, `tanstack-query`, `swr`, `mock`, `transformers`) — is documented in [Use the generated client](https://redocly.com/docs/cli/guides/use-generated-client).
@@ -27,7 +27,7 @@ import { generateClient } from '@redocly/client-generator';
 const result = await generateClient({
   api: './openapi.yaml', // file path or URL; OpenAPI 3.0/3.1/3.2 or Swagger 2.0
   output: './src/api/client.ts',
-  generators: ['sdk', 'zod'],
+  generators: ['typescript', 'zod'],
 });
 
 console.log(`Wrote ${result.files.length} file(s), ${result.bytes} bytes.`);
@@ -41,8 +41,7 @@ For type-safe authoring of a standalone options object, annotate it with `satisf
 The generated module exports its operation descriptors, so an app can build additional instances with independent configuration and credentials over the same generated code:
 
 ```ts
-import { createClient } from '@redocly/client-generator';
-import { OPERATIONS, type Ops } from './client.ts';
+import { createClient, OPERATIONS, type Ops } from './client.ts';
 
 const internal = createClient<Ops>(OPERATIONS, {
   serverUrl: 'https://api.example.com',
@@ -50,48 +49,35 @@ const internal = createClient<Ops>(OPERATIONS, {
 });
 ```
 
-With `runtime: 'package'` the generated client also imports its whole engine from this package (instead of embedding it), so engine fixes arrive via `npm update` — install this package as a regular dependency of the consuming app.
-
 ### Write a custom generator
 
 A custom generator reads the same API model the built-ins consume, runs in the same pass, and returns files.
-Build real TypeScript with the emit toolkit from `@redocly/client-generator/generate` — the same `ts.factory` + printer the built-in generators use, so the schema→type mapping matches the sdk's exactly:
+Generators print text: `Printer` handles indentation, and `tsType` is the same schema→type renderer the built-in sdk uses, so the mapping (refs, arrays, unions, formats, parenthesization) matches the generated client exactly:
 
 ```ts
 // response-map-generator.ts
-import { defineGenerator } from '@redocly/client-generator';
-import { printStatements, schemaToTypeNode, ts } from '@redocly/client-generator/generate';
-
-const { factory } = ts;
+import { defineGenerator, Printer } from '@redocly/client-generator';
+import { tsType } from '@redocly/client-generator/generate';
 
 export default defineGenerator({
   name: 'response-map',
-  requires: ['sdk'],
-  run({ model, outputPath }) {
+  requires: ['typescript'],
+  run({ model, output }) {
+    const printer = new Printer();
     // One `ResponseShapes` entry per operation with a JSON success body.
-    const members = model.services
-      .flatMap((service) => service.operations)
-      .flatMap((op) => {
-        const success = op.successResponses.find((r) => r.contentType.includes('json'));
-        if (!success) return [];
-        return [
-          factory.createPropertySignature(
-            undefined,
-            op.name,
-            undefined,
-            schemaToTypeNode(success.schema)
-          ),
-        ];
-      });
-    const alias = factory.createTypeAliasDeclaration(
-      [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
-      'ResponseShapes',
-      undefined,
-      factory.createTypeLiteralNode(members)
+    printer.block(
+      'export type ResponseShapes = {',
+      () => {
+        for (const service of model.services) {
+          for (const op of service.operations) {
+            const success = op.successResponses.find((r) => r.contentType.includes('json'));
+            if (success) printer.line(`${op.name}: ${tsType(success.schema)};`);
+          }
+        }
+      },
+      '};'
     );
-    return [
-      { path: outputPath.replace(/\.ts$/, '.responses.ts'), content: printStatements([alias]) },
-    ];
+    return [{ path: output.path.replace(/\.ts$/, '.responses.ts'), content: printer.toString() }];
   },
 });
 ```
@@ -122,12 +108,12 @@ type GenerateClientResult = {
 };
 ```
 
-`GenerateClientOptions` is the options type ([`src/types.ts`](https://github.com/Redocly/redocly-cli/blob/main/packages/client-generator/src/types.ts)) (`api` and `output` required; `outputMode`, `runtime`, `importExt`, `argsStyle`, `errorMode`, `dateType`, `serverUrl`, `mockData`, `mockSeed`, `generators`, `customGenerators`, `setup`, `pagination` optional) plus an optional resolved Redocly `config` used to load the description.
+`GenerateClientOptions` is the options type ([`src/types.ts`](https://github.com/Redocly/redocly-cli/blob/main/packages/client-generator/src/types.ts)) (`api` and `output` required; `outputMode`, `runtime`, `importExt`, `argsStyle`, `errorMode`, `dateType`, `serverUrl`, `mockData`, `mockSeed`, `generators`, `customGenerators`, `options`, `setup`, `pagination`, `queryKeyPrefix`, `goPackage`, `cliOutput`, `codeSamples`, `docs`, `docsFrontmatter` optional) plus an optional resolved Redocly `config` used to load the description.
 
 ### `collectGeneratedFiles`
 
 Runs the configured generators against a built model and returns the files in memory, without writing to disk.
-Imported from `@redocly/client-generator/generate` — the generation-time entry; the package root stays runtime-only so package-mode clients never load the generator stack:
+Imported from `@redocly/client-generator/generate` — the generation-time entry; the package root stays a small authoring surface:
 
 ```ts
 function collectGeneratedFiles(
@@ -144,13 +130,16 @@ function collectGeneratedFiles(
 
 ### `defineGenerator`
 
-Authors a custom generator (`{ name, run }` plus optional `requires`/`errorModes`/`dateTypes`/`runtimes` compatibility metadata, validated up front):
+Authors a custom generator (`{ name, run }` plus optional `requires`/`errorModes`/`dateTypes` compatibility metadata, validated up front):
 
 ```ts
 function defineGenerator(generator: CustomGenerator): CustomGenerator;
 ```
 
-The `@redocly/client-generator/generate` entry also exports the emit toolkit the built-ins use (`ts`, `printStatements`, `parseStatements`, `operationSignature`, `schemaToTypeNode`, `pascalCase`, …), and the package root exports the IR types, so a custom generator emits TypeScript exactly as the first-party ones do — see the [`ast-toolkit-generator` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/ast-toolkit-generator).
+The `@redocly/client-generator/generate` entry also exports the TypeScript renderers the built-ins use (`tsType`, `tsJsdoc`, `codeLiteral`, `operationSignature`, `pascalCase`, `safeIdent`).
+The package root exports the IR types plus the language-neutral toolkit.
+A custom generator emits TypeScript exactly as the first-party ones do.
+See the [`typescript-types-generator` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/typescript-types-generator).
 
 ### `defineClientSetup`
 
@@ -165,20 +154,9 @@ function defineClientSetup(setup: {
 
 A setup module may import only from `@redocly/client-generator`, so it never adds a dependency to the client (the import is stripped at generation time).
 
-### `createClient`
-
-The runtime factory that `runtime: 'package'` clients import, also usable directly to build extra instances over generated descriptors (see [Basic usage](#build-extra-client-instances)):
-
-```ts
-function createClient<Ops>(
-  operations: Record<string, OperationDescriptor>,
-  config?: ClientConfig
-): Client<Ops>;
-```
-
 ## Examples
 
-Runnable examples — from a zero-install quickstart to middleware, publisher setup, SSE streaming, pagination, custom generators, and the package runtime — live in [`tests/e2e/generate-client/examples`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples).
+Runnable examples — from a zero-install quickstart to middleware, publisher setup, SSE streaming, pagination, and custom generators — live in [`tests/e2e/generate-client/examples`](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples).
 Each is a standalone Vite app with a checked-in, drift-checked generated client.
 
 ## Documentation
@@ -195,8 +173,8 @@ Run all commands from the repo root:
 
 ```sh
 npm run compile                 # build this package
-npm run unit                    # unit tests (this package is held at 100% coverage)
+npm run unit                    # unit tests
 VITEST_SUITE=e2e npx vitest run tests/e2e/generate-client/   # behavioral e2e
 ```
 
-The client runtime lives in `src/runtime/` (real, unit-testable modules; package mode imports them, inline mode embeds them), the structural emitters in `src/emitters/`, the IR in `src/intermediate-representation/`, the generators in `src/generators/`, and the file-layout writers in `src/writers/`.
+Each generator that embeds a runtime keeps its sources in its own folder (`src/generators/<name>/runtime/` — real, unit-testable modules that generation embeds), the IR lives in `src/intermediate-representation/`, and the generators in `src/generators/`.

package/eject-assets/AGENTS.md

@@ -0,0 +1,137 @@
+# Writing custom client generators
+
+A generator is a plain module: `(input) => GeneratedFile[]`. It receives the
+language-agnostic API model and returns files — in ANY output language. It runs
+in the same pass as the built-ins; select it by path in `redocly.yaml`:
+
+```yaml
+client:
+  generators: [typescript, ./generators/my-generator.mjs]
+```
+
+## The contract
+
+```js
+/** @type {import('@redocly/client-generator').CustomGenerator} */
+export default {
+  name: 'my-generator',
+  run({ model, output, outputMode, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.txt'), content: '…' }];
+  },
+  // Optional: one idiomatic call snippet per operation for docs (x-codeSamples),
+  // collected into an overlay file when `client.codeSamples: true` is set.
+  sample(operation, { model, emit }) {
+    return { lang: 'python', source: '…' };
+  },
+  // Optional: the reference page for what `run` emits, written when `client.docs` (or
+  // --docs) is on. Same `{ path, content }` shape as `run`; `renderReferencePage` gives
+  // the standard layout and takes `sample` for its snippets. A generator documents itself.
+  docs({ model, output, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.md'), content: '…' }];
+  },
+};
+```
+
+## Declaring options
+
+A generator that needs configuration declares it as a schema; `run` then receives
+`options` already validated, with defaults applied:
+
+```js
+export default {
+  name: 'permissions-matrix',
+  options: {
+    type: 'object',
+    properties: { groupBy: { enum: ['tag', 'path'], default: 'tag' } },
+    additionalProperties: false,
+  },
+  run({ model, output, options }) {
+    return [
+      { path: output.path.replace(/\.ts$/, '.permissions.md'), content: render(options.groupBy) },
+    ];
+  },
+};
+```
+
+Users set them per generator name:
+
+```yaml
+client:
+  generators: [typescript, ./generators/permissions-matrix.mjs]
+  options:
+    permissions-matrix:
+      groupBy: path
+```
+
+The supported subset is a top-level `type: 'object'` with `properties`, `required`, and
+`additionalProperties`; each property is a scalar (`string`/`number`/`boolean`), an
+`enum`, or an array of scalars, and may carry a `default` and a `description`. Don't
+validate options inside `run` — an unknown key, a wrong type, a value outside an `enum`,
+or a missing `required` key already fails generation before `run` is called.
+
+Rules: output is deterministic (same description → same bytes); never add
+dependencies to the generated client; **never hand-edit generated output** —
+edit this generator and regenerate. Emitted file paths must stay inside the
+`--output` directory (subdirectories are fine) — escapes are rejected.
+Optionally declare `requiresGenerator` — the `@redocly/client-generator` version
+range you wrote this against (`'^1.2.0'`, `'~1.2.0'`, `'>=1.2.0'`, or an exact
+version). A CLI outside the range then fails with the fix path instead of feeding
+your generator an unexpected model shape. Ejected generators carry it
+automatically; hand-written ones without it are taken as current.
+
+## The model (IR)
+
+`model.services[].operations[]` — each operation carries `name`, `specName`,
+`method`, `path`, `tags`, `pathParams`/`queryParams`/`headerParams`/`cookieParams`,
+`requestBody`, `successResponses`/`errorResponses` (each with a `schema`), and
+`security`. `model.schemas` holds the named schemas. Every schema is a
+discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
+`literal`, `enum`, `union` (optionally with a discriminator), `intersection`
+(allOf), `null`, `unknown`, `omit`.
+
+## Helpers (import from '@redocly/client-generator')
+
+| Helper                                                  | Use                                                                                                                              |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `flattenAllOf(schema, model)`                           | The merged property view of allOf compositions — languages without intersection types render this.                               |
+| `deref(schema, model)`                                  | Follow a `ref` chain to the schema it names (cycle-guarded).                                                                     |
+| `jsonSuccessSchema(op)` / `sseResponse(op)`             | The primary JSON success schema; the `text/event-stream` response when the operation streams.                                    |
+| `isMultipartBody(op)`                                   | Whether the request body is multipart.                                                                                           |
+| `serverUrlParts(server)`                                | A server-URL template as literal/variable parts, ready for any concatenation syntax.                                             |
+| `securityRequirements(op, model)`                       | The operation's security as OR-alternatives of AND-sets, denormalized against the declared schemes.                              |
+| `paginationItemSchema(pageSchema, itemsPointer, model)` | The raw element schema behind a pagination rule's `items` pointer — a `ref` element keeps its name.                              |
+| `discriminatorCases(schema, model)`                     | `{ property, cases }` dispatch table for discriminated unions.                                                                   |
+| `isNullable(schema)` / `unwrapNullable(schema)`         | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                    |
+| `enumValues(schema)`                                    | Values plus SCREAMING_SNAKE member-name suggestions.                                                                             |
+| `headerCoerceType(schema, model)`                       | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                 |
+| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                          |
+| `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter. |
+| `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                               |
+| `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                             |
+| `schemaAtPointer(schema, pointer, model)`               | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type. |
+| `paginationRuleFor(op, config)`                         | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                   |
+| `renderReferencePage(model, options)`                   | The Markdown reference page a generator's `docs` hook returns — your `sample` hook supplies its call snippets.                   |
+| `NotSupportedError`                                     | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                |
+| `AUTHORING_HELPER_NAMES`                                | The list of the above (introspection).                                                                                           |
+
+Worked example: the built-in `python` generator
+(`packages/client-generator/src/generators/python/index.ts` in the Redocly CLI repo) is
+authored with exactly this toolkit and nothing else — models via `flattenAllOf`/
+`enumValues`/`discriminatorCases`, all code through `Printer`, every name through
+`identifierFor(..., RESERVED_WORDS.python)`.
+
+A generator that emits TypeScript may additionally use the source-text renderers from
+`@redocly/client-generator/generate` — `tsType` (schema → type), `tsJsdoc`, `codeLiteral`,
+`operationSignature`, `pascalCase`, `safeIdent`. There is no AST toolkit and no
+`typescript` dependency: every generator prints text through `Printer`.
+
+## The loop
+
+1. Edit the generator.
+2. Run `redocly generate-client`.
+3. Inspect `git diff` of the generated output.
+4. Repeat. Generated files are never hand-edited.
+
+If you had to work around a **missing helper** or a wrong default, tell the user
+and suggest filing an issue at https://github.com/Redocly/redocly-cli/issues —
+include the generator snippet and the helper you expected to exist.

package/eject-assets/generators/cli/docs.ts

@@ -0,0 +1,224 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+// The cli-docs emitter: renders the Markdown reference for the generated CLI from the
+// SAME command table `runCli` dispatches on, and the same `groupSlug`/`constantCase` the
+// runtime addresses groups and reads credentials with. A second model would drift from
+// the tool the first time either side changed.
+
+import {
+  type CliCommand,
+  type CliFlag,
+  constantCase,
+  groupSlug,
+  Printer,
+} from '@redocly/client-generator';
+
+export type CliDocsOptions = {
+  /** Page heading. */
+  title: string;
+  /** Emit YAML front matter carrying the title, for docs sites that expect it. */
+  frontmatter: boolean;
+  /** The generated file's stem: what the page calls the command, and what its credential
+   * variables derive from. A reader who installs it under another bin name renames only
+   * the command — the variables are fixed at generation. */
+  name: string;
+  /** Auth schemes the description declares, in the order the CLI resolves them. */
+  schemes: Array<{ key: string; kind: 'bearer' | 'basic' | 'apiKey' }>;
+};
+
+/** Table-cell-safe text: one line, and pipes/backslashes escaped so they don't alter columns/escaping. */
+function cell(text: string | undefined): string {
+  return (text ?? '').replace(/\s+/g, ' ').trim().replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+/** How a command is typed at the prompt: `<group-slug> <name>`, or just `<name>`. */
+function address(command: CliCommand): string {
+  return [command.group === undefined ? undefined : groupSlug(command.group), command.name]
+    .filter(Boolean)
+    .join(' ');
+}
+
+function usageLine(name: string, command: CliCommand): string {
+  const words = [
+    name,
+    address(command),
+    ...command.positionals.map((positional) => `<${positional.name}>`),
+    ...command.flags.filter((flag) => flag.required).map((flag) => `--${flag.name} <${flag.type}>`),
+    ...(command.body ? [command.body.required ? "--json '<json>'" : "[--json '<json>']"] : []),
+  ];
+  return words.filter((word) => word !== '').join(' ');
+}
+
+function writeFlagTable(printer: Printer, flags: CliFlag[]): void {
+  printer.line('| Flag | Type | Required | Description |');
+  printer.line('| ---- | ---- | -------- | ----------- |');
+  for (const flag of flags) {
+    const description = [
+      cell(flag.description),
+      flag.enum === undefined
+        ? ''
+        : `One of ${flag.enum.map((value) => `\`${value}\``).join(', ')}.`,
+      flag.type === 'array' ? 'Repeat the flag for multiple values.' : '',
+    ]
+      .filter((part) => part !== '')
+      .join(' ');
+    printer.line(
+      `| \`--${flag.name}\` | ${flag.type} | ${flag.required ? 'yes' : 'no'} | ${description} |`
+    );
+  }
+  printer.blank();
+}
+
+function writeCommand(printer: Printer, command: CliCommand, options: CliDocsOptions): void {
+  printer.line(`### \`${address(command)}\``);
+  printer.blank();
+  if (command.summary !== undefined) {
+    printer.line(cell(command.summary));
+    printer.blank();
+  }
+  printer.line(`\`${command.method} ${command.path}\``);
+  printer.blank();
+  printer.line('```sh');
+  printer.line(usageLine(options.name, command));
+  printer.line('```');
+  printer.blank();
+  if (command.positionals.length > 0) {
+    printer.line('| Argument | Description |');
+    printer.line('| -------- | ----------- |');
+    for (const positional of command.positionals) {
+      printer.line(`| \`<${positional.name}>\` | ${cell(positional.description)} |`);
+    }
+    printer.blank();
+  }
+  if (command.flags.length > 0) writeFlagTable(printer, command.flags);
+  const notes = [
+    command.body === undefined
+      ? ''
+      : `Takes a JSON body${command.body.required ? ' (required)' : ''}: \`--json '<json>'\`, \`--json @file.json\`, or \`--json @-\` for stdin.`,
+    command.unsupportedBody === undefined
+      ? ''
+      : `Takes a \`${command.unsupportedBody}\` body, which the CLI cannot build — call this operation through the generated client instead.`,
+    command.paginated === true
+      ? 'Paginated: `--page-all` follows every page, printing one JSON page per line.'
+      : '',
+    command.sse === true ? 'Streams server-sent events as one JSON object per line.' : '',
+    command.blob === true ? 'Returns binary content, so `--output <path>` is required.' : '',
+  ].filter((note) => note !== '');
+  for (const note of notes) printer.line(note);
+  if (notes.length > 0) printer.blank();
+}
+
+/** The whole page: heading, global flags, credentials, exit codes, then every command. */
+export function renderCliDocs(commands: CliCommand[], options: CliDocsOptions): string {
+  const printer = new Printer();
+  if (options.frontmatter) {
+    printer.line('---');
+    printer.line(`title: ${options.title}`);
+    printer.line('---');
+    printer.blank();
+  }
+  printer.line(`# ${options.title}`);
+  printer.blank();
+  printer.line(
+    `Generated command-line reference for \`${options.name}\`, produced from the API description by \`redocly generate-client\`.`
+  );
+  printer.line('Re-run generation to update it — this file is not hand-edited.');
+  printer.blank();
+
+  printer.line('## Usage');
+  printer.blank();
+  printer.line('```sh');
+  printer.line(`${options.name} <command> [flags]`);
+  printer.line(`${options.name} --help`);
+  printer.line(`${options.name} schema <command>   # request/response schemas`);
+  printer.line('```');
+  printer.blank();
+  printer.line(
+    'Install the file under any `bin` name: the command takes that name, and the credential variables below do not change.'
+  );
+  printer.blank();
+
+  printer.line('## Global flags');
+  printer.blank();
+  printer.line('| Flag | Description |');
+  printer.line('| ---- | ----------- |');
+  // `--token` mirrors the CLI itself: without a bearer scheme the tool rejects the flag,
+  // so the reference must not list it.
+  const hasBearer = options.schemes.some((scheme) => scheme.kind === 'bearer');
+  for (const [flag, description] of [
+    ['--server-url <url>', 'Override the server URL included in the client.'],
+    ['--format <json\\|ndjson>', 'Output format.'],
+    ['--dry-run', 'Print the prepared request, credentials redacted, without sending it.'],
+    ['--page-all', 'Follow pagination, printing one JSON page per line.'],
+    ['--output <path>', 'Write the response body to a file. Required for binary responses.'],
+    ...(hasBearer ? [['--token <token>', 'Bearer token, overriding the environment.']] : []),
+    ['--json <json\\|@file\\|@->', 'Request body, inline or from a file or stdin.'],
+  ] as const) {
+    printer.line(`| \`${flag}\` | ${description} |`);
+  }
+  printer.blank();
+
+  const prefix = constantCase(options.name);
+  printer.line('## Credentials');
+  printer.blank();
+  if (options.schemes.length === 0) {
+    printer.line('The description declares no security schemes, so no credentials are read.');
+  } else {
+    printer.line('Credentials come from the environment:');
+    printer.blank();
+    printer.line('| Scheme | Variable |');
+    printer.line('| ------ | -------- |');
+    for (const scheme of options.schemes) {
+      const variable =
+        scheme.kind === 'bearer'
+          ? `\`${prefix}_TOKEN\` (or \`--token\`)`
+          : scheme.kind === 'basic'
+            ? `\`${prefix}_USERNAME\` and \`${prefix}_PASSWORD\``
+            : `\`${prefix}_API_KEY_${constantCase(scheme.key)}\``;
+      printer.line(`| ${scheme.kind} (\`${scheme.key}\`) | ${variable} |`);
+    }
+  }
+  printer.blank();
+
+  printer.line('## Exit codes');
+  printer.blank();
+  printer.line('| Code | Meaning |');
+  printer.line('| ---- | ------- |');
+  for (const [code, meaning] of [
+    [0, 'success'],
+    [1, 'API error (status other than 401 or 403)'],
+    [2, 'auth error (401 or 403)'],
+    [3, 'validation error'],
+    [4, 'usage error (unknown command or flag, bad `--json`)'],
+  ] as const) {
+    printer.line(`| ${code} | ${meaning} |`);
+  }
+  printer.blank();
+  printer.line('Errors print one JSON object to stderr, so stdout stays clean for piping.');
+  printer.blank();
+
+  // One section per tag, in the order the description declares them, then the untagged
+  // commands — the same order `--help` lists them in.
+  const groups = [...new Set(commands.map((command) => command.group))];
+  for (const group of groups) {
+    const inGroup = commands.filter((command) => command.group === group);
+    if (group === undefined) {
+      printer.line('## Commands');
+      printer.blank();
+    } else {
+      printer.line(`## ${group}`);
+      printer.blank();
+      printer.line(`Addressed as \`${options.name} ${groupSlug(group)} <command>\`.`);
+      printer.blank();
+    }
+    for (const command of inGroup) writeCommand(printer, command, options);
+  }
+  return (
+    printer
+      .toString()
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd() + '\n'
+  );
+}

package/eject-assets/generators/cli/engine-source.ts

@@ -0,0 +1,21 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+// The cli engine's embeddable source, snapshotted at prepare time (see
+// scripts/generate-runtime-sources.mjs).
+
+import {
+  RUNTIME_SOURCES,
+  RUNTIME_SOURCES_STRIPPED,
+} from '@redocly/client-generator/runtime-sources';
+
+/** The cli engine (`runCli` + types) stripped for embedding into `<stem>.cli.ts`. */
+export function embedCliRuntime(): string {
+  return RUNTIME_SOURCES_STRIPPED['cli.ts'];
+}
+
+/** The cli engine RAW, for `runtime: 'module'` (written as `runtime/cli.ts`). */
+export function cliRuntimeSource(): string {
+  return RUNTIME_SOURCES['cli.ts'];
+}

package/eject-assets/generators/cli/index.ts

@@ -0,0 +1,90 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "cli" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator cli --update`.
+import {
+  type CodeSample,
+  type Generator,
+  groupSlug,
+  type OperationModel,
+  type SampleContext,
+} from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderCliDocs } from './docs.ts';
+import { cliRuntimeSource } from './engine-source.ts';
+import { cliAuthSchemes, commandData, renderCliModule } from './render.ts';
+
+/**
+ * The cli generator: a bin-ready `<stem>.cli.ts` — a zero-dependency, typed
+ * command-line interface over the sibling client (typed flags, `--json`
+ * bodies, env auth, `--page-all`, SSE/blob output, a documented exit-code
+ * contract). Requires `typescript` (throw mode); wires zod validation when co-selected.
+ */
+export const cliGenerator: Generator = ({ model, output, banner, emit, selected, pagination }) => {
+  const content = renderCliModule(model, {
+    stem: output.stem,
+    importExt: emit.importExt ?? 'js',
+    zodSelected: selected?.includes('zod') ?? false,
+    pagination,
+    argsStyle: emit.argsStyle ?? 'grouped',
+    runtime: emit.runtime ?? 'inline',
+  });
+  const entry = { path: join(output.dir, `${output.stem}.cli.ts`), content };
+  if (emit.runtime !== 'module') return [entry];
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  return [
+    entry,
+    {
+      path: join(output.dir, 'runtime', 'cli.ts'),
+      content: `${header}\n\n${cliRuntimeSource().trim()}\n`,
+    },
+  ];
+};
+
+/**
+ * The CLI's own reference page, written when `client.docs` is on: the usage line, the
+ * global flags, the credential variables, the exit codes, and one section per command.
+ * It renders from `commandData` — the same table `runCli` dispatches on — so the page
+ * cannot describe a tool other than the one beside it.
+ */
+export const cliDocs: Generator = ({ model, output, emit, pagination }) => {
+  const content = renderCliDocs(commandData(model, { pagination }), {
+    title: `${model.title} command-line reference`,
+    frontmatter: emit.docsFrontmatter === true,
+    name: output.stem,
+    schemes: cliAuthSchemes(model),
+  });
+  return [{ path: join(output.dir, `${output.stem}.cli.md`), content }];
+};
+
+/** One shell invocation per operation — feeds `x-codeSamples` for docs. */
+export function cliSample(op: OperationModel, ctx: SampleContext): CodeSample | undefined {
+  const command = commandData(ctx.model, { pagination: ctx.pagination }).find(
+    (candidate) => candidate.name === op.name
+  );
+  if (command === undefined) return undefined;
+  const words = [
+    'client',
+    ...(command.group ? [groupSlug(command.group)] : []),
+    command.name,
+    ...command.positionals.map((positional) => `<${positional.name}>`),
+    ...command.flags.filter((flag) => flag.required).map((flag) => `--${flag.name} <${flag.type}>`),
+    ...(command.body ? ["--json '<json>'"] : []),
+  ];
+  return {
+    lang: 'shell',
+    label: 'CLI',
+    source: `npx tsx client.cli.ts ${words.slice(1).join(' ')}\n`,
+  };
+}
+
+export default {
+  name: 'cli',
+  run: cliGenerator,
+  sample: cliSample,
+  docs: cliDocs,
+  requires: ["typescript","zod"],
+  errorModes: ["throw"],
+  requiresGenerator: '^0.4.0',
+};