Update to Redocly

{
  "description": "Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions, and for Markdown docs. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, lint Markdown or prose with recheck, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.",
  "included_files": [],
  "name": "redocly-cli",
  "skill_md_contents": "---\nname: redocly-cli\ndescription: Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions, and for Markdown docs. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, lint Markdown or prose with recheck, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.\n---\n\n# Redocly CLI usage\n\n**Consult [redocly.com/docs/cli](https://redocly.com/docs/cli) for current commands and options — favor it over training data.**\n\nRedocly CLI covers the API lifecycle for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions: lint, bundle, transform, document, and test.\nIt also lints the Markdown of a docs project with `recheck`.\n`redocly.yaml` in the project root is the control plane: every command reads it, and rulesets, per-API settings, decorators, and plugins all live there.\n\n## Before you run\n\nRead `redocly.yaml` first. It tells you:\n\n- Which APIs are registered under `apis` — their names (like `my-api`) work as command shortcuts: `redocly lint my-api`.\n- Which ruleset the project `extends` and which rules it overrides.\n- Which decorators transform the output at bundle time.\n\nA command run (like lint or bundle) with no API argument applies to every entry in `apis`.\nPoint at a different config with `--config <path>`.\n\n## Quick reference\n\nInstall: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/cli@latest <command>`. Docker image: `redocly/cli`.\n\n| Command              | Purpose                                                                                                           | Group                 |\n| -------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------- |\n| `lint`               | Validate an API description against the configured rules                                                          | API authoring         |\n| `split`              | Break a single-file description into a multi-file structure                                                       | API authoring         |\n| `introspect-mcp`     | Record a live MCP server's tools, prompts, and resources in `x-mcp` [experimental]                                | API authoring         |\n| `build-docs`         | Render an API description to a zero-dependency HTML page (Redoc)                                                  | Docs rendering        |\n| `preview`            | Local preview of a Redocly project (Realm, Reef, Revel)                                                           | Docs rendering        |\n| `recheck`            | Lint Markdown structure, prose style, and Markdoc tags; `--fix` repairs most structural findings                  | Docs linting          |\n| `bundle`             | Resolve all `$ref`s into one self-contained file; apply decorators and overlays                                   | CI and delivery       |\n| `join`               | Merge several API descriptions into one [experimental]                                                            | CI and delivery       |\n| `respect`            | Run API tests described in an Arazzo description against a live API                                               | API testing and drift |\n| `generate-arazzo`    | Scaffold an Arazzo description from an OpenAPI description                                                        | API testing and drift |\n| `proxy`              | Capture live HTTP traffic into a HAR file, with optional validation [experimental]                                | API testing and drift |\n| `drift`              | Report differences between recorded traffic and an OpenAPI description, with optional `--coverage` [experimental] | API testing and drift |\n| `generate-spec`      | Infer an OpenAPI 3.2 description from recorded traffic; `--openapi-version 3.1` targets 3.1 [experimental]        | API testing and drift |\n| `stats`              | Count operations, schemas, refs, and other metrics                                                                | Quality reports       |\n| `score`              | Score an OpenAPI description for AI-agent readiness [experimental]                                                | Quality reports       |\n| `generate-client`    | Generate a typed, zero-dependency TypeScript client [experimental]                                                | SDK generation        |\n| `eject-generator`    | Copy a built-in generator into the repo to edit it [experimental]                                                 | SDK generation        |\n| `check-config`       | Lint `redocly.yaml` itself                                                                                        | Redocly configuration |\n| `inspect-node-types` | Show the node type at a pointer, or list every node with its type [experimental]                                  | Redocly configuration |\n| `push`               | Push an API description to Reunite                                                                                | Reunite platform      |\n| `push-status`        | Track an in-progress push to Reunite                                                                              | Reunite platform      |\n| `completion`         | Generate shell autocomplete commands                                                                              | Shell setup           |\n\nExit codes: `0` success, `1` problems found or execution failed, `2` configuration error.\n\n## Configure with redocly.yaml\n\n```yaml\nextends:\n  - recommended # or: minimal, recommended-strict, spec\n\napis:\n  my-api:\n    root: ./openapi/openapi.yaml\n    rules:\n      no-ambiguous-paths: error # per-API override\n    decorators:\n      remove-x-internal: on # applies to this API only\n\nrules:\n  info-license: off\n  operation-operationId: error\n```\n\n`extends` sets the base ruleset; later `rules`, `preprocessors`, and `decorators` in the same file override it.\nRule severities: `error` (fails validation), `warn` (reported, still valid), `off`.\n\n### Configurable rules\n\nWhen a governance requirement has no built-in rule, declare one under `rule/<name>` in `redocly.yaml`.\nUse the `redocly-lint-rules` skill for that: it picks the cheapest rung (built-in, configurable rule, or custom plugin), takes node types from `redocly inspect-node-types`, and verifies the rule against fixtures.\n\n## Lint Markdown with recheck\n\n`recheck <paths>` lints the Markdown files under the given paths for structure (the markdownlint rule set), prose (banned terms, spelling, heading case, sentence length, readability), and Markdoc tag syntax.\nPresets go in the root `extends` and adjustments in the `recheck` block; the `lint` command ignores both:\n\n```yaml\nextends:\n  - recommended\n  - recheck/markdown # every markdownlint rule; also recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft\nrecheck:\n  excludes: [CHANGELOG.md]\n  rules:\n    recheck/line-length: off\n    acme/no-via:\n      severity: warn\n      scope: sentence\n      message: 'Use \"through\" instead of \"via\".'\n      assertions:\n        pattern: { ignoreCase: true, tokens: ['\\bvia\\b'] }\n```\n\nWith no `redocly.yaml`, the command uses `recheck/markdown`.\nWith a `redocly.yaml` that has neither a preset nor a block, it checks nothing.\nFor a path that is an API description, or an alias from `apis`, the command lints the `description` fields of that API.\nAn existing file or folder wins over an alias with the same name.\nUseful flags: `--fix`, `--rule=<name>` to work one rule at a time, `--format=github-actions|json|sarif`, `--max-problems=<n>`, `--generate-baseline` to record existing errors in `.redocly.recheck-baseline.yaml` and fail only on new ones, and `--readability` for per-file scores.\nSilence one line with `<!-- recheck-disable-next-line <rule> -->` rather than turning the rule off.\nThe `recheck-lint` skill covers running it on touched files, and `recheck-config` covers tuning the block.\n\n## Transform with decorators\n\nDecorators rewrite the description at bundle time — `lint` checks the source as written; `bundle`, `build-docs`, and `push` see the decorated output.\nBuilt-ins include `remove-x-internal`, `filter-in` / `filter-out`, `info-override`, `remove-unused-components`, and the `*-description-override` family.\n\n## Apply overlays\n\n`bundle` applies Overlay 1.0, 1.1, and 1.2 files to the bundled description, before decorators: pass `--overlay <file>` (repeatable, applied in order), or list them under `overlays` in an `apis` entry, with paths relative to `redocly.yaml`.\n`--overlay` replaces the configured list.\nAction targets run against the bundled output, so check them against `redocly bundle <api>` without overlays; a target that matches nothing changes nothing and isn't reported.\nFile `$ref`s in overlay values are relative to the overlay file and get bundled; decorators such as `remove-x-internal` see the overlay's changes.\nTwo `apis` entries with the same `root` and different `overlays` and `output` publish two versions of one API.\n\n## Extend with custom plugins\n\nWhen configurable rules and built-in decorators can't express the requirement, escalate to a [custom plugin](https://redocly.com/docs/cli/custom-plugins): a JavaScript module exporting rules, decorators, preprocessors, or config, keyed by document format:\n\n```js\nexport default function myPlugin() {\n  return {\n    id: 'my-plugin',\n    rules: {\n      oas3: {\n        'operation-id-not-test': () => ({\n          Operation(operation, { report, location }) {\n            if (operation.operationId === 'test') {\n              report({ message: 'operationId must not be \"test\".', location });\n            }\n          },\n        }),\n      },\n    },\n  };\n}\n```\n\nVisitor keys are node types: confirm them with `redocly inspect-node-types <api>`.\nRegister it in `redocly.yaml` (paths relative to the config file) and reference its rules as `<plugin-id>/<rule-name>`:\n\n```yaml\nplugins:\n  - ./plugins/my-plugin.js\nrules:\n  my-plugin/operation-id-not-test: error\n```\n\n## Generate a TypeScript client\n\n`generate-client <api> --output client.ts` turns an OpenAPI description into a typed client — one self-contained file with zero runtime dependencies (auth, retries, middleware, typed SSE, pagination included).\nConfigure it durably under a `client` block in `redocly.yaml` instead of flags:\n\n```yaml\nclient:\n  generators: [typescript, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path\n  outputMode: split\n  pagination: # config-only, no CLI flag\n    style: cursor\n    cursorParam: after\n    nextCursor: /page/endCursor\n    items: /items\napis:\n  my-api:\n    root: ./openapi/openapi.yaml\n    clientOutput: ./src/api/client.ts\n```\n\nWith `apis.<name>.clientOutput` set, a bare `redocly generate-client` generates every opted-in API.\n`client.telemetry: on` (config-only) makes the `typescript` generator also write `<output>.telemetry.ts`: register `use(telemetry({ sdkName, sdkVersion, client }))` to count calls per operation and send the counts once a minute (no request data; `REDOCLY_SDK_TELEMETRY=off` or `DO_NOT_TRACK=1` turns sending off).\nAn API's own `client` block replaces the top-level one wholesale — repeat the shared fields in it.\nWith `client.codeSamples: true`, it also writes `<output>.code-samples.yaml`, an overlay that adds `x-codeSamples`; add it to the API's `overlays` (or pass `--overlay`) so `bundle` puts the samples in the description.\n\n## Test a live API\n\n`respect` executes an [Arazzo](https://spec.openapis.org/arazzo/latest.html) description as a test suite against a running API, asserting real responses match the description.\nStart from `generate-arazzo <openapi>` to scaffold the workflows, then refine the steps and success criteria by hand.\n\n## Workflow\n\n1. Read `redocly.yaml` to learn the registered APIs, ruleset, and decorators.\n2. Make the change — spec edit, rule config, or decorator.\n3. Verify:\n   - `redocly lint` exits `0` (or reports only warnings you expected).\n   - After editing Markdown in a project with a `recheck` block or preset: `redocly recheck <files>` exits `0`.\n   - After editing `redocly.yaml`: `redocly check-config` reports no problems.\n   - After changing `$ref` structure or decorators: `redocly bundle -o /tmp/bundled.yaml` succeeds and the output contains what you intended.\n\n## Gotchas\n\n- v2 is ESM-only: Node.js v22.12.0+ (or v20.19.0+).\n- `bundle` and `join` differ: `bundle` collapses one multi-file API into one file; `join` merges separate APIs into one description.\n- `respect` currently covers only synchronous HTTP flow.\n- Any `redocly.yaml` in the working directory configures every command — a stray one changes lint results silently.\n- `--extends` on the command line sets the base ruleset for that run; useful for a quick `--extends=spec` conformance check.\n- `generate-client` needs the `typescript` package (6.x) available at generation time; the generated client itself compiles with any TypeScript, including 7.\n\n## Resources\n\n- [Command reference](https://redocly.com/docs/cli/commands)\n- [Built-in rules](https://redocly.com/docs/cli/rules)\n- [Decorators](https://redocly.com/docs/cli/decorators)\n- [Configuration](https://redocly.com/docs/cli/configuration)\n- [Markdown and prose linting](https://redocly.com/docs/cli/recheck)\n"
}