Choose the most appropriate installation method for your needs:
- Install locally, using
npmto make theredoclycommand available on your system. - Use
npxto get the tool at runtime rather than installing it. - Download a standalone binary that runs without Node.js.
- The command is also available through Docker.
Before you begin, make sure you have the newest version of npm.
To install Redocly CLI locally:
- In your CLI,
cdto your project's directory. - Enter the following command:
npm i @redocly/cli@latest
- (Optional) Run
redocly --versionto confirm that the installation was successful and the currently-installed version of the tool.
npx is npm's package runner. It installs and runs a command without installing it globally.
Use this approach where you can't install a new command, or in a CI context where the command is only used a handful of times.
To run Redocly CLI with npx:
Replace
redoclywithnpx @redocly/cli@latestto prepend Redocly CLI commands.npx @redocly/cli@latest <command> [options]
For example, to run redocly lint on a file named openapi.yaml, use the following command:
npx @redocly/cli@latest lint openapi.yaml
Starting with version 2.81.0, every Redocly CLI release on the GitHub releases page includes standalone binaries for Linux, macOS, and Windows. A binary doesn't need Node.js or npm. The SHA256SUMS file in the same release lists the SHA-256 checksum of each binary.
| System | File |
|---|---|
| Linux x64 | redocly-linux-x64 |
| Linux arm64 | redocly-linux-arm64 |
| Linux x64 with musl, such as Alpine | redocly-linux-x64-musl |
| Linux arm64 with musl, such as Alpine | redocly-linux-arm64-musl |
| macOS with an Intel processor | redocly-darwin-x64 |
| macOS with an Apple silicon processor | redocly-darwin-arm64 |
| Windows x64 | redocly-windows-x64.exe |
| Windows arm64 | redocly-windows-arm64.exe |
The musl binaries need the C++ standard library. On Alpine, install it with apk add libstdc++.
To install a binary on Linux or macOS:
Download the binary for your system and the checksums file. Replace the version and the file name with the ones you need:
VERSION=2.81.0 FILE=redocly-linux-x64 curl -fLO "https://github.com/Redocly/redocly-cli/releases/download/%40redocly%2Fcli%40$VERSION/$FILE" curl -fLO "https://github.com/Redocly/redocly-cli/releases/download/%40redocly%2Fcli%40$VERSION/SHA256SUMS"Check the binary against its checksum:
sha256sum --check --ignore-missing SHA256SUMSOn macOS, use
shasum -a 256 --check --ignore-missing SHA256SUMS.Make the binary executable and move it to a folder on your
PATH:chmod +x "$FILE" sudo mv "$FILE" /usr/local/bin/redoclyRun
redocly --versionto confirm the installation.
On Windows, download the .exe file and the SHA256SUMS file. In PowerShell, run Get-FileHash redocly-windows-x64.exe and compare the hash with the line for the same file in SHA256SUMS. Then rename the file to redocly.exe and add its folder to your PATH.
The macOS binaries are not notarized by Apple. MacOS blocks binaries downloaded in a web browser. Download the binary with the previously mentioned curl command, or remove the block with xattr -d com.apple.quarantine <file>.
The preview, eject, and translate commands download their product package from the npm registry and run it on the runtime built into the binary. They use the registry configured in your .npmrc file. preview doesn't run on Windows arm64, because the framework depends on a database library with no build for that platform.
Redocly CLI is available as a pre-built Docker image in Docker Hub and GitHub Packages.
Before you begin, make sure you have Docker installed.
To run Redocly CLI commands inside a docker container:
- Pull the image:
docker pull redocly/cli
- To give a Docker container access to your OpenAPI description files, mount the containing directory as a volume:
docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml
This example assumes that the API description file is in your current working folder.
To run the CLI tool behind a proxy, you can use the HTTP_PROXY and HTTPS_PROXY environment variables to configure the proxy settings. These environment variables specify the proxy server for HTTP and HTTPS traffic, respectively.
To set the proxy environment variables:
- Open a terminal and use the following command:
export HTTP_PROXY=http://your-http-proxy-server:port
Use the NO_PROXY environment variable to specify hosts that should be accessed directly, without going through the proxy. The value is a comma-separated list of hostnames or domain suffixes:
localhost— exact hostname match..example.com— matches any subdomain ofexample.com(but notexample.comitself).example.com— matchesexample.comand any subdomain such asapi.example.com.*— bypasses the proxy for all requests.
To directly include the proxy environment variables in a Redocly CLI command:
Prepend the command with the environment variable and its value.
For example:
HTTPS_PROXY=https://your-https-proxy-server:port redocly lint --extends minimal openapi.yaml
- Set up autocomplete for Redocly CLI.
- Check the full list of Redocly CLI commands available.
- Try things out with the Museum Example API.