Skip to content
Last updated

Install Redocly CLI

Choose the most appropriate installation method for your needs:

Install locally

Before you begin, make sure you have the newest version of npm.

To install Redocly CLI locally:

  1. In your CLI, cd to your project's directory.
  2. Enter the following command:
npm i @redocly/cli@latest
  1. (Optional) Run redocly --version to confirm that the installation was successful and the currently-installed version of the tool.

Use the command at runtime

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 redocly with npx @redocly/cli@latest to 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

Download a standalone binary

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.

SystemFile
Linux x64redocly-linux-x64
Linux arm64redocly-linux-arm64
Linux x64 with musl, such as Alpineredocly-linux-x64-musl
Linux arm64 with musl, such as Alpineredocly-linux-arm64-musl
macOS with an Intel processorredocly-darwin-x64
macOS with an Apple silicon processorredocly-darwin-arm64
Windows x64redocly-windows-x64.exe
Windows arm64redocly-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:

  1. 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"
    
  2. Check the binary against its checksum:

    sha256sum --check --ignore-missing SHA256SUMS
    

    On macOS, use shasum -a 256 --check --ignore-missing SHA256SUMS.

  3. Make the binary executable and move it to a folder on your PATH:

    chmod +x "$FILE"
    sudo mv "$FILE" /usr/local/bin/redocly
    
  4. Run redocly --version to 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.

Run commands inside Docker

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:

  1. Pull the image:
docker pull redocly/cli
  1. 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.

Run CLI behind a proxy

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.

Set up Proxy Environment Variables

To set the proxy environment variables:

  • Open a terminal and use the following command:
export HTTP_PROXY=http://your-http-proxy-server:port

Bypass proxy for specific hosts

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 of example.com (but not example.com itself).
  • example.com — matches example.com and any subdomain such as api.example.com.
  • * — bypasses the proxy for all requests.

Use Environment Variables with CLI Commands

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
    

Next steps