# Redocly CLI for OpenAPI linting and documentation > Redocly CLI is a TypeScript command-line tool for working with OpenAPI, AsyncAPI, and Arazzo descriptions. It combines linting, bundling, reference documentation, contract testing, and related API lifecycle tasks, with configuration-driven rules for teams that need repeatable API checks. **Redocly/redocly-cli** — ⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more. - Repository: https://github.com/Redocly/redocly-cli - Website: https://redocly.com/docs/cli/ - Stars: 1,538 · Forks: 232 - Language: TypeScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/redocly-redocly-cli ## Redocly CLI's API lifecycle scope Redocly CLI addresses a specific documentation and governance problem: API descriptions often contain validation errors, inconsistent conventions, or references across several files, and the same description may need different processing during development, review, CI, and publication. The project is intended for API maintainers, developers, documentation teams, and organizations that apply standards during the API lifecycle. Its README describes support for OpenAPI 3.x and 2.0, including legacy Swagger, as well as AsyncAPI 3.x and 2.6, Arazzo 1.x, and other formats. The tool is not only a documentation renderer. The `lint` command checks descriptions against API rules, `bundle` recombines documents connected through `$ref`, and `build-docs` uses the open source Redoc project to produce reference documentation. Respect is presented as a separate community-edition contract testing system included in the CLI workflow. This gives the project a broad surface, but it also means adoption depends on which of those tasks the team actually needs. The documentation positions rules as a mechanism for API governance. Built-in rules can be combined or customized, and custom rules and plugins are possible. Output formats include `stylish`, JSON, Markdown, and Checkstyle, which matters when findings must be consumed by CI or another tool. The README states that multiple files can be linted through an entry point, so a team does not have to produce one bundled file before every check. Redocly CLI is primarily a command-line utility. Its repository contains TypeScript packages, tests, plugins, documentation, cookbook examples, and agent skills. It does not present itself here as a hosted service. The README mentions Redocly's commercial Reunite offering for hosted API management and describes Respect Monitoring as a broader commercial product with continuous monitoring features. Those offerings should not be confused with what the community-edition CLI itself performs locally. ## Commands and the processing path The README's basic invocation starts with an API description and passes it to a command. Linting follows the entry document and its related files, checking them against the configured ruleset. Bundling addresses a different but related problem: a description split across files with `$ref` can be assembled into one output document for tools that do not handle the original structure. Documentation generation consumes an API description and uses Redoc to render a static reference page. Respect generates workflows from OpenAPI and then sends real HTTP requests to an API server, comparing returned responses with the expectations defined in the description or Arazzo workflow. This separation matters. A successful lint run says that configured checks passed or produced findings. It does not by itself prove that a running service behaves according to its schema. Contract testing has a different execution boundary because it needs a reachable API server and sends requests to it. Documentation generation has a different output boundary because it produces an HTML file, by default `redoc-static.html`. The CLI supports multiple specification families, but that breadth should not be read as identical behavior for every format. The README names supported OpenAPI, AsyncAPI, and Arazzo versions, yet it does not provide a complete command-by-command compatibility matrix in the shown instructions. The actual support for a particular field, command, or rule needs to be checked in the command documentation and the project's rules documentation. The project also includes a Docker image. The Dockerfile uses `node:24-alpine`, installs build dependencies, runs the preparation and packaging steps, installs the generated package globally, and sets `WORKDIR /spec` and `ENTRYPOINT ["redocly"]`. The container therefore expects an API description to be available under `/spec` when the user supplies a mounted volume. ## Installing Redocly CLI and running the first lint The README offers three practical installation paths. A one-off invocation with `npx` is suitable for trying the tool or using it in automation without a global installation. A global npm installation provides the `redocly` command. Docker is useful when the team wants a fixed container workflow and needs to mount the directory containing the API description. For a first local check, the README gives this one-off command. It points at an existing entry file, so replace the example filename with the path used by the project. ```sh npx @redocly/cli@latest lint path-to-root-file.yaml ``` The command should either report that the description satisfies the active rules or print lint findings. The README does not define a single output filename or a success code for this invocation, so the team should use the documentation for the selected lint output format and the behavior of its CI runner. If the command is installed globally, the installation and first invocation are: ```sh npm install @redocly/cli -g ``` ```sh redocly lint path-to-root-file.yaml ``` The global installation creates the `redocly` executable described by the README. The project also documents a Docker route. With the API description rooted in the current working directory, the command is: ```sh docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml ``` The volume mount is required according to the README so the container can access the description files. A locally built image uses these commands from the project root: ```sh docker build -t redocly/cli . ``` ```sh docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml ``` For documentation generation, the first real output is static HTML: ```sh redocly build-docs openapi.yaml ``` The README states that the result is `redoc-static.html` by default. The build-docs documentation is the source for customization options, so teams needing a different output name or layout should check that command documentation rather than assuming every Redoc option is exposed through the same file. The repository package metadata states Node.js `>=22.12.0 || >=20.19.0 <21.0.0` and npm `>=11`, while the README's installation section states minimum Node.js `22.12.0` and npm `10.9.2`. Those are different version statements in the available documentation. A team should verify which requirement applies to its intended release and npm environment before automating installation. ## Respect contract tests and client-generation boundaries Redocly CLI includes a contract-testing workflow called Respect. According to the README, Respect sends real HTTP requests to an API server and validates responses against expectations defined in the OpenAPI description and Arazzo workflows. Its stated checks cover response agreement with the OpenAPI schema, complex request sequences described through Arazzo, API drift in development and CI/CD, behavior of external APIs, response times, and anomaly detection. The documented quick start has two distinct phases. The first generates an Arazzo workflow from an OpenAPI description: ```sh redocly generate-arazzo openapi.yaml ``` The second runs the generated workflow against the API, with verbose output enabled: ```sh redocly respect auto-generated.arazzo.yaml --verbose ``` This is not equivalent to static linting. The first phase derives a test workflow from the source description, while the second phase depends on an API server that can receive requests. If the service is unavailable, incorrectly deployed, or not reachable from the test environment, the documented contract test path cannot produce the normal response comparison. The README does not document authentication setup for arbitrary servers, so that configuration must come from the Respect command documentation. The README also introduces a TypeScript client generator, but labels it experimental and warns that flags, output, and configuration may change in any minor release until stability is declared. That is a direct adoption risk for pipelines that depend on generated client structure. Pinning the package version and reviewing generated output is more defensible than treating the feature as a stable interface, The distinction between community CLI features and commercial products is important. Respect is identified as the community-edition contract testing system. Respect Monitoring is described as offering real-time insights, automated alerts through email or Slack, automatic API checks, and proactive quality assurance. The CLI documentation does not establish that those monitoring capabilities are included in the local CLI. ## Configuration, maintenance, and MIT licensing Redocly CLI is written primarily in TypeScript and is distributed under the MIT license. The repository's default branch is `main`, it is not archived, and the last push was on 2026-10-16. The recent push supports describing the repository as receiving recent development, but it does not establish a release cadence, compatibility policy, or long-term support window. Maintenance status should be judged from those exact facts rather than from the number of packages or releases listed. The package metadata describes a private root package at version `2.0.0` with workspace packages under `packages/*`. It defines scripts for compilation, type checking, unit and end-to-end tests, linting with `oxlint`, formatting with `oxfmt`, and preparation with Husky. Contributors therefore need more than the published CLI if they intend to work on the repository itself. A contributor checkout needs the Node.js and npm versions supported by the package metadata, followed by the repository's normal dependency and preparation workflow. The README points to a migration guide for users moving from Redocly CLI v1 to v2, which indicates that command or configuration behavior may require review during a major-version migration. The MIT license permits use, modification, distribution, and sublicensing subject to its conditions, including preservation of the copyright and license notice. This is a factual summary of the license type's scope, not legal advice. Teams should read `LICENSE.md` and any separate notices for dependencies, generated files, or commercial Redocly components relevant to their distribution. The main operational cost is likely configuration and review cost rather than a separate runtime service in the documented community workflow. Teams must choose or write rules, decide which output format CI should consume, maintain specification references, and validate generated documentation and Respect workflows. The README does not document rollback behavior, upgrade automation, or a compatibility matrix, so those points require direct verification in the migration guide and command documentation. ## Conclusion Adopt Redocly CLI when API descriptions need linting, bundling, documentation, or contract tests in local development and CI workflows. Do not adopt it as a general-purpose API server, a hosted monitoring platform, or a fully stable client generator without first checking the Node.js, npm, configuration, and experimental feature boundaries documented by the project. The first verification should be the chosen lint ruleset, the supported specification versions, and whether every required operation is stable. ## FAQ ### What Node.js and npm versions does Redocly CLI require? The README states minimum versions of Node.js 22.12.0 and npm 10.9.2. The repository package metadata separately specifies `>=22.12.0 || >=20.19.0 <21.0.0` for Node.js and `>=11` for npm, so verify the requirement for the release you install. ### How do I run Redocly CLI against an OpenAPI file? The README gives `npx @redocly/cli@latest lint path-to-root-file.yaml` as a one-off invocation. After a global installation, use `redocly lint path-to-root-file.yaml`. ### Can Redocly CLI test a running API? Yes, through the documented Respect workflow. The README shows `redocly generate-arazzo openapi.yaml` followed by `redocly respect auto-generated.arazzo.yaml --verbose`, which sends requests to an API server and checks responses against the description and workflow. ## Sources - [License: MIT](https://github.com/Redocly/redocly-cli/blob/main/LICENSE) - [Project website](https://redocly.com/docs/cli/) - [README](https://github.com/Redocly/redocly-cli/blob/main/README.md) - [Redocly/redocly-cli on GitHub](https://github.com/Redocly/redocly-cli) - [Releases](https://github.com/Redocly/redocly-cli/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/redocly-redocly-cli