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.
Visit the installation page to find and use an installation method that works for you:
redoclyas a command (recommended, and used in the other examples in this article)
npxto run the command without installing the package
dockerto run the command
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.
Replace the old
redoc-cli serve with:
redocly preview-docs --use-community-edition openapi.yaml
The documentation will update when the spec file changes.
By default the documentation is available on
http://127.0.0.1:8080 but this is configurable.
--use-community-edition parameter is needed for the tool to use Redoc to generate the docs; otherwise it generates the preview for our hosted API reference docs
preview-docs documentation for more information and examples
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.
If you have your OpenAPI description split between multiple files, replace
redoc-cli bundle with
redocly bundle openapi.yaml -o all-in-one.yaml
Details and examples of using
bundle are on the
bundle command page. Learn more about bundling, dereferencing, and handling unused components.
Some of the configuration options have been updated. This section shows how to check which of your settings should be changed.
Two of the configuration settings were renamed for consistency with the rest of the Redocly tools.
In both cases, the child options should work as before.
Replace your existing
--options.theme.* settings with a new prefix:
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
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.
features.openapi.* should be re-prefixed to
theme.openapi.*, either at the top level of the configuration, or per API. So a configuration file to change one of the colours to a rather lurid purple would look something like the example below:
theme: 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
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
It's recommended to uninstall
redoc-cli now that it is no longer needed