CLI Generator

The cli generator — its skill

This file is the DESIGN of your ejected cli generator (generators/cli/): to change the generator, edit this skill first, then make the code match it — a diff to generators/cli/ that has no covering sentence here is incomplete.

What it emits

A bin-ready <stem>.cli.ts: one command per operation over the sdk's instance client, with --help, a schema <op> introspection command, and --dry-run.

With client.docs (or --docs), the docs hook also writes <stem>.cli.md: the usage line, the global flags, the credential variables, the exit-code table, and one section per command with its positionals and flags.

Design decisions that must hold

• Argument shape: path params positional, query params typed --kebab-name flags, JSON bodies via --json '<json>' | @file | @- (stdin).

• Help is the whole interface. A flag that exists but isn't in --help doesn't exist to the user, so the top-level help carries a Global flags: section (--server-url, --format, --dry-run, --page-all, --output, --token, --json) plus the credential environment variables. Descriptions are collapsed to ONE line — an OpenAPI description with newlines otherwise breaks the alignment of every following flag. The footer names the form that actually works for a grouped API (<bin> <group> <command> --help).

• Commands are addressable the way a shell allows. A group slug is kebab-cased so a multi-word OpenAPI tag can be typed without quoting, while help shows the original tag. A bare operationId resolves to its grouped command when unambiguous.

• Exit codes are a contract: 0 ok, 1 API error, 2 auth, 3 validation, 4 usage. Errors print ONE JSON object to stderr so stdout stays pipeable.

• The CLI names itself from process.argv[1]. Only the operator's bin field decides what the command is called, so help reads the invoked name back instead of printing a name from generation that may not exist on the machine.

• Credentials come from the environment — wiring.envPrefix, the constant-cased output stem (CLIENT_TOKEN), which a composed entry sets per api alias — or explicit flags; --dry-run prints the prepared request with credentials REDACTED. The prefix is fixed at generation on purpose: a renamed binary must keep reading the variables a published CLI already documents. Help lists only the credentials the description declares, and an unusable --token is a usage error, never silently dropped.

• Validation is on by default. The generator declares requires: ['typescript', 'zod'] and the pipeline pulls prerequisites in automatically, so --generator cli alone produces a validating CLI — a user shouldn't have to know which other generator provides it. The consequence is a zod peer dependency at run time, which the docs state.

• Throw-mode only — the exit-code mapping reads thrown ApiErrors.

• Runs under node --experimental-strip-types with no build step, including the modules it imports (the sdk and the zod module). Anything emitted must be erasable TypeScript; a parameter property anywhere in that import graph breaks the zero-build runner.

• The generated module is a library as well as a binary. It exports COMMANDS, wiring, and run, and self-executes only when it is the process entry — a REALPATH comparison of import.meta.url against argv[1], because some runners resolve symlinks in one but not the other (macOS temp dirs, installed bin symlinks), and a plain URL comparison silently runs nothing. import.meta.main would be cleaner but is absent from our Node floors. Importing the module must be side-effect-safe: module-level wiring (zod validation) touches only the module's OWN client, never a global.

• Behavior that is not in the description is composed, never generated. A custom command (login, anything) is the operation-command data shape plus a handler, so it inherits help, parsing, schema, and the exit-code contract; runCli dispatches it instead of the client. The generator itself never learns what such a command does — credentials files, login flows, and profiles are user land (or a future satellite), by design.

• One binary can span several descriptions. runCli also accepts sources — each a command list plus, optionally, its OWN wiring (own base URL, schemes, credentials) behind a namespace, so colliding operationIds across descriptions are simply different commands (cafe shop createOrder, cafe kitchen createOrder). A namespace-less source puts commands at the root (cafe login); a root command whose name matches a namespace is rejected at startup, never shadowed. A source WITHOUT wiring inherits the first wired source's — a root login shares the composed binary's identity, which is the whole point of composing it there.

• The composed entry is generated, not hand-rolled. A top-level client.cliOutput makes redocly generate-client (no api argument) emit one entry over every api that selected cli: the namespace is the api ALIAS from apis:, and the credential prefix defaults to <BINNAME>_<ALIAS> (CAFE_SHOP_TOKEN) via wiring.envPrefix — which exists precisely so the display name and the credential prefix can differ. The composed entry exports its SOURCES so an adopter layers custom commands around it without editing a generated file. Without cliOutput, nothing changes.

• The CLI documents itself. The page is this generator's docs hook, not a separate generator: nothing else knows this tool's commands, and a reader who ejects cli gets the page layout with it. The page renders from commandData — the same table runCli dispatches on — so it cannot describe a tool other than the one beside it. A capability reaches the page only by being in that table. The page is Markdown that survives a linter (ATX headings, a blank line around every block, no hard tabs, one sentence per line) and it escapes what descriptions contain, because a summary is arbitrary text.

The stage files

render.ts derives commandData from the IR and renders the module and the composed entry; docs.ts renders the reference page from the same command table; engine-source.ts supplies the cli engine's source text — the engine itself (runCli, the parser, help, dispatch) ships inside the package and arrives through @redocly/client-generator/runtime-sources (in this repo it lives in runtime/cli.ts beside these files). index.ts is the entry. The sdk calling convention comes from @redocly/client-generator/contracts/typescript.

Ejecting it

redocly eject-generator cli copies this generator's TypeScript source folder to generators/cli/, exactly as we wrote it, importing @redocly/client-generator, @redocly/client-generator/contracts/typescript, @redocly/client-generator/runtime-sources (the embedded cli engine), and @redocly/openapi-core. Running a .ts generator uses Node's type stripping (Node 22.18, 23.6, or newer); newer built-in versions merge in per file with --update. Change the command surface, the help layout, or the exit-code mapping, and regenerate. The exit codes are a contract for scripts, so change them only deliberately.

The modify loop

1. Edit this skill: state the new behavior or decision.
2. Make generators/cli/ match it.
3. Run redocly generate-client and inspect the git diff of the generated output — generated files are never hand-edited.

Newer built-in versions merge in with redocly eject-generator cli --update.