Migrate to Redocly CLI from redoc-cli

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This guide shows how to replace old redoc-cli commands with the updated Redocly CLI equivalents. We strongly recommend that all users upgrade as soon as they can.

Prepare the tools

Visit the installation page to find and use an installation method that works for you:

• Install redocly as a command (recommended, and used in the other examples in this article)
• Use npx to run the command without installing the package
• Use docker to run the command

Replace old commands with new ones

All Redocly CLI commands use a common configuration file. For theme options, linting rules, and other configuration, check out the configuration documentation for all the details.

Publish documentation

Replace existing redoc-cli build commands with:

redocly build-docs openapi.yaml

This generates a zero-dependency HTML file with your docs in, named redoc-static.html by default.

Bundle OpenAPI description

If you have your OpenAPI description split between multiple files, replace redoc-cli bundle with redocly bundle:

redocly bundle openapi.yaml -o all-in-one.yaml

Update configuration settings

Some of the configuration options have been updated. This section shows how to check which of your settings should be changed.

Renamed fields

Two of the configuration settings were renamed for consistency with the rest of the Redocly tools.

• Replace menu with sidebar
• Replace codeSample with codeBlock

In both cases, the child options should work as before.

Update command-line configuration

Replace your existing --options.theme.* settings with a new prefix: --theme.openapi.theme.*.

For example if you used redoc-cli build --options.theme.sidebar.width='300px' openapi.yaml then the new command would be:

redocly build-docs --theme.openapi.theme.sidebar.width='300px' openapi.yaml

Update configuration file

Configuration belongs in a file named redocly.yaml, or in a file name specified with the --config command-line parameter. You can read more about the configuration file structure in the documentation, and changes between this and older versions are listed here.

Re-name options that begin with features.openapi.* to openapi.*. Do this either at the top level of the configuration, or per API. A configuration file to change one of the colours to a rather lurid purple would look something like the following example:

openapi:
  theme:
    colors:
      primary:
        main: '#ff00ff'

Define the base customization; older versions of the tools defaulted to using recommended, but this is no longer assumed. Set it in redocly.yaml like this:

extends:
  - recommended

Next steps with Redocly CLI

The newer tool has a lot more functionality than redoc-cli had, so explore the rest of the Redocly CLI documentation to find out more about:

• Ensuring API quality with linting
• Managing large OpenAPI files
• Enhancing an OpenAPI description with decorators