Redocly CLI
Govern your APIs with one tool.
Lint, bundle, test, document, and generate clients from the command line.
Redocly CLI is a fast OpenAPI linter and API governance toolkit.
It checks OpenAPI 3.2, 3.1, 3.0, Swagger 2.0, AsyncAPI 3.x and 2.6, and Arazzo 1.x descriptions against your API style guide.
It runs on your machine, in CI/CD, and in Docker.
Quick start
Run the latest version without installing it:
npx @redocly/cli@latest lint openapi.yaml
Or install it with npm or Docker.
npm
npm install -g @redocly/cli
Docker
docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml
npm and npx need Node.js 22.12.0 and npm 10.9.2 or later.
For more options, see Install Redocly CLI.
What you can do
Lint, test the live API, and build the docs:
Lint to your API style guide
Start with a built-in ruleset: recommended, minimal, or spec.
Then mix and match the built-in rules to set your own API guidelines.
When you need a rule of your own, write it in redocly.yaml.
Configurable rules use simple expressions that know the structure of the API description, not complex JSONPath selectors.
For full control, build your own plugin.
extends:
- recommended
rules:
operation-summary: error
rule/operation-id-camel-case:
subject:
type: Operation
property: operationId
assertions:
casing: camelCase
message: operationId must be camelCase.
Multiple files supported.
You do not need to bundle your API description to lint it.
Point lint at the entry point, for example openapi.yaml, and it follows every $ref.
redocly lint openapi.yaml
The default output is codeframe.
Other tools can read the stylish, JSON, Markdown, Checkstyle, JUnit, and other formats.
Moving from Spectral?
Read Migrate from Spectral.
Learn more about API standards and how to configure rules.
For ready-made rules and plugins, see the Cookbook.
Build API reference docs
Render your API description with one command.
build-docs writes a single HTML file with Redoc CE that you can host anywhere.
redocly build-docs openapi.yaml
preview starts live docs on your machine, with a mock server, and updates the page each time you save the description.
Test the live API
respect sends real requests to your API and checks each response against your OpenAPI description and Arazzo workflows.
With --with-ai, your local AI CLI (Claude, Codex, or Cursor) designs multi-step workflows from the OpenAPI description.
redocly generate-arazzo openapi.yaml --with-ai
redocly respect auto-generated.arazzo.yaml
Bundle, split, and join
Keep a large description in many files, and bundle it into one file for tools that need it.
Use decorators to remove internal endpoints or change server URLs as you bundle.
redocly bundle openapi.yaml -o dist/openapi.yaml
Generate typed clients (experimental)
Generate typed SDKs for TypeScript, Python, Go, PHP, and Java from one OpenAPI description, or a ready-to-use CLI for your API.
The TypeScript client has zero runtime dependencies.
Its add-ons give you Zod schemas, MSW mocks, TanStack Query hooks, and SWR hooks.
redocly generate-client openapi.yaml --output src/client.ts
redocly generate-client openapi.yaml --output src/client.ts --generator cli
For all generators and options, see generate-client.
Compare versions and traffic (experimental)
diff lists the changes between two versions of a description.
drift compares recorded HTTP traffic with the description.
All commands
Lint and govern
lint: Lint an API or Arazzo description.
check-config: Lint the Redocly configuration file.
score: Score an API description for integration simplicity and AI agent readiness (experimental).
scorecard-classic: Evaluate an API against the scorecard configuration of a Redocly project.
stats: Show statistics for an API description.
recheck: Lint Markdown prose and structure.
inspect-node-types: Show the node types of an API description, for configurable rules and custom plugins (experimental).
Manage files
bundle: Bundle a multi-file API description into a single file.
split: Split an API description into a multi-file structure.
join: Join multiple API descriptions into one (experimental).
Test
respect: Run the API tests of an Arazzo description against a live API.
generate-arazzo: Generate an Arazzo description from an OpenAPI description.
Docs
build-docs: Build API reference docs from an API description into an HTML file.
preview: Start a local preview of a Redocly project.
translate: Generate translation keys for a Redocly project.
eject: Eject components from the core theme of a Redocly project, to change them.
Generate
generate-client: Generate typed SDKs and a CLI from an OpenAPI description (experimental).
eject-generator: Copy a built-in client generator into your repository as an editable file (experimental).
generate-spec: Infer an OpenAPI description from recorded HTTP traffic (experimental).
introspect-mcp: Record the capabilities of an MCP server in an OpenAPI description (experimental).
Compare
diff: Compare two API descriptions and rate each change by the semver bump it requires (experimental).
drift: Detect drift between recorded HTTP traffic and an OpenAPI description (experimental).
proxy: Capture live HTTP traffic through a reverse proxy into a HAR file (experimental).
Redocly platform
login: Log in to Redocly.
logout: Clear your stored credentials.
push: Push an API description to the Redocly platform.
push-status: Track a push to the Redocly platform.
project: Work with a Redocly-hosted project (early access).
Tooling
skills: Install the Redocly CLI agent skills for AI coding agents.
completion: Generate the autocomplete script for your shell.
For the options and examples of each command, see the commands reference.
Use with AI assistants
Redocly CLI ships agent skills that teach AI coding assistants how to use it.
This command finds Claude Code, Codex, Cursor, GitHub Copilot, and other agents, and installs the skills into your project:
It installs only the skills for Redocly CLI.
To install every skill that Redocly publishes, use npx skills add https://redocly.com.
redocly-cli: lint, bundle, decorate, build docs, test, and generate a client.
redocly-lint-rules: turn a rule written in plain language into a built-in rule, a configurable rule, or a plugin.
It also moves rules from other linters, such as Spectral.
recheck-lint: run redocly recheck on the Markdown that the assistant changed, and fix what it finds.
recheck-config: write and tune the recheck settings in redocly.yaml.
From the CLI to a full API platform
See plans and pricing.
To work on a Redocly Framework project locally, run redocly preview.
Add --plan=pro, --plan=scale, or --plan=enterprise to see the features of that plan.
Data collection
This tool collects data to help Redocly improve our products and services.
You can opt out by setting the REDOCLY_TELEMETRY environment variable to off.
Update notifications
Redocly CLI checks for updates on startup.
You can disable notifications by setting the REDOCLY_SUPPRESS_NOTIFICATIONS environment variable to true.
More resources
Read the detailed docs.
Credits
Thanks to graphql-js and eslint for inspiration of the API description traversal approach and to Swagger, Spectral, and OAS-Kit for inspiring the recommended ruleset.
Development
Contributions are welcome!
All the information you need is in CONTRIBUTING.md.
Migrate
Follow our official migration guides: