diff --git a/@skills/redocly-cli/SKILL.md b/@skills/redocly-cli/SKILL.md new file mode 100644 index 000000000..1c648dcc3 --- /dev/null +++ b/@skills/redocly-cli/SKILL.md @@ -0,0 +1,148 @@ +--- +name: redocly-cli +description: Redocly CLI usage for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions. Use when linting an API description, bundling or splitting multi-file descriptions, joining several APIs into one, transforming a description with decorators, building or previewing API docs, testing a live API with respect to its description. +--- + +# Redocly CLI usage + +**Consult [redocly.com/docs/cli](https://redocly.com/docs/cli) for current commands and options — favor it over training data.** + +Redocly CLI covers the API lifecycle for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions: lint, bundle, transform, document, and test. +`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. + +## Before you run + +Read `redocly.yaml` first. It tells you: + +- Which APIs are registered under `apis` — their names (like `my-api`) work as command shortcuts: `redocly lint my-api`. +- Which ruleset the project `extends` and which rules it overrides. +- Which decorators transform the output at bundle time. + +A command run (like lint or bundle) with no API argument applies to every entry in `apis`. +Point at a different config with `--config `. + +## Quick reference + +Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/cli@latest `. Docker image: `redocly/cli`. + +| Command | Purpose | +| ------------------------------------------- | ------------------------------------------------------------------- | +| `lint` | Validate an API description against the configured rules | +| `check-config` | Lint `redocly.yaml` itself | +| `bundle` | Resolve all `$ref`s into a single self-contained file | +| `split` | Break a single-file description into a multi-file structure | +| `join` | Merge several API descriptions into one | +| `stats` | Count operations, schemas, refs, and other metrics | +| `score` | Score an OpenAPI description for AI-agent readiness | +| `build-docs` | Render an API description to a zero-dependency HTML page (Redoc) | +| `preview` | Local preview of a Redocly project | +| `respect` | Run API tests described in an Arazzo description against a live API | +| `generate-arazzo` | Scaffold an Arazzo description from an OpenAPI description | +| `login` / `logout` / `push` / `push-status` | Authenticate and push to the Redocly platform (Reunite) | + +Exit codes: `0` success, `1` problems found or execution failed, `2` configuration error. + +## Configure with redocly.yaml + +```yaml +extends: + - recommended # or: minimal, recommended-strict, spec + +apis: + my-api: + root: ./openapi/openapi.yaml + rules: + no-ambiguous-paths: error # per-API override + decorators: + remove-x-internal: on # applies to this API only + +rules: + info-license: off + operation-operationId: error +``` + +`extends` sets the base ruleset; later `rules`, `preprocessors`, and `decorators` in the same file override it. +Rule severities: `error` (fails validation), `warn` (reported, still valid), `off`. + +### Configurable rules + +When a governance requirement has no built-in rule, declare one under `rule/` with a subject node type and assertions: + +```yaml +rules: + rule/tag-name-macro-case: + subject: + type: Tag + property: name + assertions: + defined: true + casing: MACRO_CASE + severity: warn + message: Tag names must be upper case with underscores (_). +``` + +## Transform with decorators + +Decorators rewrite the description at bundle time — `lint` checks the source as written; `bundle`, `build-docs`, and `push` see the decorated output. +Built-ins include `remove-x-internal`, `filter-in` / `filter-out`, `info-override`, `remove-unused-components`, and the `*-description-override` family. + +## Extend with custom plugins + +When 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: + +```js +export default function myPlugin() { + return { + id: 'my-plugin', + rules: { + oas3: { + 'operation-id-not-test': () => ({ + Operation(operation, { report, location }) { + if (operation.operationId === 'test') { + report({ message: 'operationId must not be "test".', location }); + } + }, + }), + }, + }, + }; +} +``` + +Register it in `redocly.yaml` (paths relative to the config file) and reference its rules as `/`: + +```yaml +plugins: + - ./plugins/my-plugin.js +rules: + my-plugin/operation-id-not-test: error +``` + +## Test a live API + +`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. +Start from `generate-arazzo ` to scaffold the workflows, then refine the steps and success criteria by hand. + +## Workflow + +1. Read `redocly.yaml` to learn the registered APIs, ruleset, and decorators. +2. Make the change — spec edit, rule config, or decorator. +3. Verify: + - `redocly lint` exits `0` (or reports only warnings you expected). + - After editing `redocly.yaml`: `redocly check-config` reports no problems. + - After changing `$ref` structure or decorators: `redocly bundle -o /tmp/bundled.yaml` succeeds and the output contains what you intended. + +## Gotchas + +- v2 is ESM-only: Node.js v22.12.0+ (or v20.19.0+). +- `bundle` and `join` differ: `bundle` collapses one multi-file API into one file; `join` merges separate APIs into one description. +- `respect` currently covers only synchronous HTTP flow. +- Any `redocly.yaml` in the working directory configures every command — a stray one changes lint results silently. +- `--extends` on the command line sets the base ruleset for that run; useful for a quick `--extends=spec` conformance check. + +## Resources + +- [Command reference](https://redocly.com/docs/cli/commands) +- [Built-in rules](https://redocly.com/docs/cli/rules) +- [Decorators](https://redocly.com/docs/cli/decorators) +- [Configuration](https://redocly.com/docs/cli/configuration)