Skip to content

About

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.

Topics

Resources

Contributing

Stars

1.6k stars

Watchers

20 watching

Forks

Latest commit

 

History

2,561 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Redocly CLI

Govern your APIs with one tool. Lint, bundle, test, document, and generate clients from the command line.

npm version npm downloads per month License Build and test

The API lifecycle with Redocly CLI: lint, test, document, generate, and compare, on every change, locally and in CI.

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:

Redocly CLI lints a multi-file API description, tests a live API, and builds API reference 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.

redocly preview

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:

redocly skills

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

Redocly Platform: publish what you lint. Interactive API docs, a mock server, and an API catalog, published from your Git repository. Start a 30-day free trial.

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:

About

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.

Topics

Resources

Contributing

Stars

1.6k stars

Watchers

20 watching

Forks

Releases

Packages

Used by

Contributors

Languages