[opensourcedex]

redocly-cli is a free, open source api development & testing project written in TypeScript and released under MIT. It has 1,510 GitHub stars, 228 forks and 166 open issues, and was last pushed 10 hours ago. On this registry it ranks #131 of 180 tracked projects in API Development & Testing, with 5 head-to-head comparisons available.

What is redocly-cli?

Redocly CLI is a TypeScript, MIT-licensed command-line toolset that lints, bundles, validates, tests, and renders OpenAPI, AsyncAPI, and Arazzo descriptions, built for API designers, platform teams, and CI pipelines that need API governance and reference documentation without adopting a hosted service.

What it is

Redocly CLI is an all-in-one command-line utility for API descriptions. It builds, manages, improves, and quality-checks API definitions across the phases of the API lifecycle. It reads OpenAPI 3.x and 2.0 (legacy Swagger), AsyncAPI 3.x and 2.6, Arazzo 1.x, and other formats, and it runs on Node.js or as a container image. The project lives in the OpenAPI and AsyncAPI tooling ecosystem, is written in TypeScript, and is distributed on npm as @redocly/cli under the MIT licence.

The concrete problem it solves is the fragmentation of a spec pipeline across single-purpose tools. Teams split a large API description into many documents linked by $ref, then discover that downstream tooling cannot follow $ref or handle multiple documents; the bundle command recombines those documents into one clean file. Teams that want API guidelines enforced across an organisation otherwise write their own checks or adopt another linter such as Spectral; the lint command applies built-in or custom rulesets instead, and the project documents migrating rules from other linters. Rendering reference documentation is folded into the same binary through open source Redoc rather than being a separate build step.

Key capabilities

  • The lint command checks an API description against expected API guidelines, using built-in rulesets or custom ones written as a built-in rule, a configurable rule, or a custom plugin.
  • The bundle command recombines descriptions that were split across multiple documents with $ref into a single output document.
  • The build-docs command renders API reference documentation using open source Redoc, writing redoc-static.html by default.
  • The preview command runs Redoc, Revel, Reef, and Realm locally.
  • The test command supports contract testing of API descriptions, and the toolset also covers decorating descriptions and generating a client.
  • Format support covers OpenAPI 3.x and 2.0 (legacy Swagger), AsyncAPI 3.x and 2.6, and Arazzo 1.x.
  • Two agent skills, redocly-cli and redocly-lint-rules, teach AI coding assistants to work with the CLI and can be installed with npx skills add https://redocly.com.

Who uses it and how

  • API platform and governance teams that enforce consistent naming conventions and security rules across many descriptions by running lint in CI/CD pipelines.
  • Design-first API teams that shape an API's design before it exists by linting the description alongside the design workflow.
  • Teams maintaining large, heavily $ref-split descriptions that need a single bundled artifact for tools that do not follow references.
  • Documentation owners who generate static API reference output in a build step rather than hosting a separate documentation product.
  • Developers working with AI coding assistants that install the shipped agent skills for day-to-day lint, bundle, decorate, docs, test, and client generation tasks.

Getting started

Run it without installing with npx @redocly/cli@latest lint path-to-root-file.yaml, or install it globally with npm install @redocly/cli -g and use it as redocly [command] [options]. A container image is also published: mount the description directory as a volume and run docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml. Node.js 22.12.0 and npm 10.9.2 are the minimum supported versions.

How it compares

Among tools named in the project's own documentation, Spectral is the other linter the migration guidance targets, and Redocly CLI documents how to move rules from it; Redoc is the open source renderer that Redocly CLI drives for documentation output. Redocly itself also offers a hosted API management solution at redocly.com/reunite, described as a commercial alternative to Redoc, which places the CLI as the self-hosted, MIT-licensed option alongside a paid managed product. Teams upgrading from an earlier major version are pointed at a dedicated migration guide for moving from v1 to v2.

When to use it — and when not to

Choose it when API descriptions already live in a repository and linting, bundling, and documentation generation should happen in the same pipeline, on a self-hosted Node.js 22.12.0 or later runtime or in a Docker container with the spec directory mounted as a volume. Avoid it if the team wants a fully managed documentation and API management service rather than operating the toolchain itself, since a commercial hosted option exists for that case. Be aware that the repository carries 166 open issues and that the v1 to v2 transition requires following a migration guide, so existing v1 configurations should be reviewed before upgrading.

project readme (upstream, from github) — read inline

Redocly CLI

@Redocly CLI is your all-in-one API documentation utility. It builds, manages, improves, and quality-checks your API descriptions, all of which comes in handy for various phases of the API Lifecycle. Create your own rulesets to make API governance easy, publish beautiful API reference documentation, and more. Supports OpenAPI 3.x and 2.0 (legacy Swagger), AsyncAPI 3.x and 2.6, Arazzo 1.x, and more.

build and test npm (scoped) NPM

OpenAPI CLI toolset

Migration

Migrating from Redocly CLI v1 to v2? Here's the guide to make the transition smoother.

Usage

Node

npx @redocly/cli@latest lint path-to-root-file.yaml

Alternatively, install it globally with npm:

npm install @redocly/cli -g

Then you can use it as redocly [command] [options], for example:

redocly lint path-to-root-file.yaml

The minimum required versions of Node.js and NPM are 22.12.0 and 10.9.2 respectively.

Docker

To give the Docker container access to the OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is rooted in the current working directory, you need the following command:

docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml

To build and run with a local image, run the following from the project root:

docker build -t redocly/cli .
docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml

Use with AI assistants

Redocly CLI ships agent skills that teach AI coding assistants how to work with the CLI. Install them into your project:

npx skills add https://redocly.com
  • redocly-cli — day-to-day usage: lint, bundle, decorate, build docs, test, and generate a client.
  • redocly-lint-rules — turn a check written in plain language into a built-in rule, a configurable rule, or a custom plugin. It also covers migrating rules from other linters, such as Spectral.

Common tasks

Generate API reference documentation

Redocly CLI is a great way to render API reference documentation. It uses open source Redoc to build your documentation. Use a command like this:

redocly build-docs openapi.yaml

Your API reference docs are in redoc-static.html by default. You can customize this in many ways. Read the main docs for more information.

:bulb: Redocly also has hosted API management solution, a (commercial) alternative to Redoc. Redoc, Revel, Reef, and Realm can be worked on locally using the preview command.

Bundle multiple OpenAPI documents

Having one massive OpenAPI description can be annoying, so most people split them up into multiple documents via $ref, only to later find out some tools don't support $ref or don't support multiple documents. Redocly CLI to the rescue! It has a bundle command you can use to recombine all of those documents back into one single document. The bundled output that Redocly CLI provides is clean, tidy, and looks like a human made it.

Automate API guidelines with Linting

Check that your API matches the expected API guidelines by using the lint command. API guidelines are an important piece of API governance. They help to keep APIs consistent by enforcing the same standards and naming conventions, and they can also guide API teams through potential security hazards and other pitfalls. Automating API guidelines means you can keep APIs consistent and secure throughout their lifecycle. Even better, you can shape the design of the API before it even exists by combining API linting with a design-first API workflow.

Our API linter is designed for speed on even large documents, and it's easy to run locally, in CI, or anywhere you need it. It's also designed for humans, with meaningful error messages to help you get your API right every time.

Try it like this:

redocly lint openapi.yaml

Configure the rules as you wish. Other API Linters use complicated identifiers like JSONPath, but Redocly makes life easy with simple expressions that understand the API specification structure. You can either use the built-in rules to mix-and-match your ideal API guidelines, or break out the tools to build your own.

Format the output in whatever way you need. The stylish output is as good as it sounds, but if you need JSON, Markdown, Checkstyle and other outputs to integrate with other tools, the lint command can output those too.

Multiple files supported so you don't need to bundle your API description to lint it; just point Redocly CLI at the "entry point" (e.g.: openapi.yaml) and it handles the rest.

Learn more about API standards and configuring Redocly rules.

Looking for more examples? Check out our Cookbook.

API contract testing with Respect

Ensure your APIs match their OpenAPI descriptions with Respect, Redocly's API contract testing system. Respect sends real HTTP requests to your API server and validates that responses match the expectations defined in your OpenAPI description and Arazzo workflows.

  • Verify API responses match your OpenAPI schema
  • Test complex API sequences using OpenAPI Arazzo format
  • Catch API drift early in development and CI/CD
  • Ensure external APIs you depend on behave as expected
  • Track response times and detect anomalies
Quick start
# Generate test workflows from your OpenAPI spec
redocly generate-arazzo openapi.yaml

# Run contract tests against your API
redocly respect auto-generated.arazzo.yaml --verbose
Respect vs. Respect Monitoring

Respect is Redocly's community-edition product. Looking for something more? We also offer continuous API monitoring with additional features including:

  • Real-time insights
  • Automated alerts via email or Slack
  • Automated API checks
  • Proactive API quality assurance

Learn more about Respect and get started with API contract testing.

Generate a TypeScript client

⚠️ Experimental — flags, output, and configuration may change in any minor release until declared stable.

Turn an OpenAPI description (3.0/3.1/3.2 or Swagger 2.0) into a typed TypeScript client with the generate-client command. The emitted client has zero runtime dependencies and runs in browsers, Node, Bun, Deno, and edge runtimes.

redocly generate-client openapi.yaml --output src/client.ts

Inline types plus a typed client instance and one async function per operation, with auth, opt-in abort-aware retries, middleware, and typed Server-Sent Events. The same command can also emit Zod schemas, TanStack Query / SWR hooks, MSW mocks, and more via --generator. For detailed information, read the generate-client docs.

Transform an OpenAPI description

If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly decorators feature. This allows you to:

  • Publish reference docs with a subset of endpoints for public use
  • Improve the docs by adding examples and descriptions
  • Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms

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 this by setting the REDOCLY_SUPPRESS_UPDATE_NOTICE 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.

Frequently asked questions

Is redocly-cli free to use?

redocly-cli is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does redocly-cli do?

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

What is redocly-cli written in?

redocly-cli is primarily written in TypeScript. Its source is publicly available at https://github.com/Redocly/redocly-cli, and it has 1,510 GitHub stars.