# Redocly CLI

> Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions. Use when the user wants to lint, bundle, split, or join an API description, apply decorators, build or preview API docs, 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.

- Skill: `redocly/redocly-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redocly/redocly-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redocly/redocly-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: redocly (https://skillmd.com/u/redocly)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redocly/redocly-cli

---


# 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 <path>`.

## Quick reference

Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/cli@latest <command>`. Docker image: `redocly/cli`.

| Command              | Purpose                                                                               | Group                 |
| -------------------- | ------------------------------------------------------------------------------------- | --------------------- |
| `lint`               | Validate an API description against the configured rules                              | API authoring         |
| `split`              | Break a single-file description into a multi-file structure                           | API authoring         |
| `introspect-mcp`     | Record a live MCP server's tools, prompts, and resources in `x-mcp` [experimental]    | API authoring         |
| `build-docs`         | Render an API description to a zero-dependency HTML page (Redoc)                      | Docs rendering        |
| `preview`            | Local preview of a Redocly project (Realm, Reef, Revel)                               | Docs rendering        |
| `bundle`             | Resolve all `$ref`s into a single self-contained file and apply decorators            | CI and delivery       |
| `join`               | Merge several API descriptions into one [experimental]                                | CI and delivery       |
| `respect`            | Run API tests described in an Arazzo description against a live API                   | API testing and drift |
| `generate-arazzo`    | Scaffold an Arazzo description from an OpenAPI description                            | API testing and drift |
| `proxy`              | Capture live HTTP traffic into a HAR file, with optional validation [experimental]    | API testing and drift |
| `drift`              | Report differences between recorded traffic and an OpenAPI description [experimental] | API testing and drift |
| `generate-spec`      | Infer an OpenAPI description from recorded traffic [experimental]                     | API testing and drift |
| `stats`              | Count operations, schemas, refs, and other metrics                                    | Quality reports       |
| `score`              | Score an OpenAPI description for AI-agent readiness [experimental]                    | Quality reports       |
| `generate-client`    | Generate a typed, zero-dependency TypeScript client [experimental]                    | SDK generation        |
| `eject-generator`    | Copy a built-in generator into the repo to edit it [experimental]                     | SDK generation        |
| `check-config`       | Lint `redocly.yaml` itself                                                            | Redocly configuration |
| `inspect-node-types` | Show the node type at a pointer, or list every node with its type [experimental]      | Redocly configuration |
| `push`               | Push an API description to Reunite                                                    | Reunite platform      |
| `push-status`        | Track an in-progress push to Reunite                                                  | Reunite platform      |
| `completion`         | Generate shell autocomplete commands                                                  | Shell setup           |

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/<name>` in `redocly.yaml`.
Use 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.

## 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 });
            }
          },
        }),
      },
    },
  };
}
```

Visitor keys are node types: confirm them with `redocly inspect-node-types <api>`.
Register it in `redocly.yaml` (paths relative to the config file) and reference its rules as `<plugin-id>/<rule-name>`:

```yaml
plugins:
  - ./plugins/my-plugin.js
rules:
  my-plugin/operation-id-not-test: error
```

## Generate a TypeScript client

`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).
Configure it durably under a `client` block in `redocly.yaml` instead of flags:

```yaml
client:
  generators: [typescript, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path
  outputMode: split
  pagination: # config-only, no CLI flag
    style: cursor
    cursorParam: after
    nextCursor: /page/endCursor
    items: /items
apis:
  my-api:
    root: ./openapi/openapi.yaml
    clientOutput: ./src/api/client.ts
```

With `apis.<name>.clientOutput` set, a bare `redocly generate-client` generates every opted-in API.
An API's own `client` block replaces the top-level one wholesale — repeat the shared fields in it.

## 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 <openapi>` 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.
- `generate-client` needs the `typescript` package (6.x) available at generation time; the generated client itself compiles with any TypeScript, including 7.

## 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)