Redocly/redocly-cli / packages/client-generator/eject-assets/skills/cli-generator
cli-generator
UnverifiedDesign of the ejected Redocly `cli` client generator. Read it, and update it, before changing generators/cli/.
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-nameflags, JSON bodies via--json '<json>' | @file | @-(stdin). -
Help is the whole interface. A flag that exists but isn't in
--helpdoesn't exist to the user, so the top-level help carries aGlobal 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'sbinfield 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-runprints 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--tokenis 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 clialone 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-typeswith 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, andrun, and self-executes only when it is the process entry — a REALPATH comparison ofimport.meta.urlagainstargv[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.mainwould 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 ahandler, so it inherits help, parsing,schema, and the exit-code contract;runClidispatches 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.
runClialso 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 rootloginshares 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.cliOutputmakesredocly generate-client(no api argument) emit one entry over every api that selectedcli: the namespace is the api ALIAS fromapis:, and the credential prefix defaults to<BINNAME>_<ALIAS>(CAFE_SHOP_TOKEN) viawiring.envPrefix— which exists precisely so the display name and the credential prefix can differ. The composed entry exports itsSOURCESso an adopter layers custom commands around it without editing a generated file. WithoutcliOutput, nothing changes. -
The CLI documents itself. The page is this generator's
docshook, not a separate generator: nothing else knows this tool's commands, and a reader who ejectscligets the page layout with it. The page renders fromcommandData— the same tablerunClidispatches 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
- Edit this skill: state the new behavior or decision.
- Make
generators/cli/match it. - Run
redocly generate-clientand inspect thegit diffof the generated output — generated files are never hand-edited.
Newer built-in versions merge in with redocly eject-generator cli --update.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |