Redocly OpenAPI CLI

Redocly OpenAPI CLI is an open source command-line tool used to:

• Lint and bundle your OpenAPI definition(s).
• Decorate your APIs (add or remove data).
• Preview reference docs for local development.
• Split single-file OpenAPI files into a multi-file format.
• Integrate with Redocly's API registry.
• Build production-ready reference docs (requires an Enterprise license key).

Redocly OpenAPI CLI can be:

• Extended by writing custom rules and decorators.

Features

Currently, Redocly OpenAPI CLI supports these features:

• Multi-file validation. No need to bundle your files before validation.
• Support for remote $refs.
• Configurable severity levels for each rule. Tailor your experience with Redocly OpenAPI CLI to suit your needs.
• Lightning-fast validation. Check a 1 MB file in less than one second.
• Human-readable error messages. Now with stacktraces and codeframes.
• Intuitive suggestions for misspelled types or references.
• Easy-to-implement custom rules. Need something? Ask us or do it yourself.
• Bundle a multi-file definition into a single file for compatibility with external tools.
• Preview reference docs.
• Support for OAS 3.0 and Swagger 2.0 (OAS 3.1 is coming soon).

What makes Redocly OpenAPI CLI different

Unlike other OpenAPI validators, Redocly OpenAPI CLI defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how compilers work, and results in major performance benefits over other approaches.

Redocly OpenAPI CLI comes with a set of built-in rules, but you can extend its functionality by creating your own rules. Both the lint and the bundle features follow the visitor pattern for adding custom behavior on the parsed object.

Lint

Bundle

Installation and usage

You can install and use OpenAPI CLI in any of these ways:

• npx (NPM's package runner)
• npm -g (NPM's global installation)
• npm (NPM as a package local to a project)
• yarn global (Yarn's global installation)
• yarn (Yarn as a package local to a project)
• docker (use a Docker image)

Global installations

Install globally with npm

npm install -g @redocly/openapi-cli@latest

Install globally with yarn

yarn global add @redocly/openapi-cli

Verify your global installation

After installing it globally, run openapi --version to confirm the installation was successful.

Set up tab completion

OpenAPI CLI supports the tab completion functionality.

To set it up for your terminal, generate the completion script with the command:

openapi completion

The command output contains installation instructions. For example, to install the completion script in bash, use:

openapi completion >> ~/.bashrc

The approach is similar for other shells. After the installation, restart your terminal for changes to take effect.

Runtime installations

Install and use with npx

NPX is NPM's package runner. It will install and run a command at the same time (without installing it globally).

npx @redocly/openapi-cli <command> [options]

Here is a sample command:

npx @redocly/openapi-cli@latest lint

Install and use with docker

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

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

Using OpenAPI CLI commands

Read more about supported commands in Redocly OpenAPI CLI.

Contributions

The source code is available in the OpenAPI-CLI GitHub repository.