Redocly CLI is the recommended replacement for the deprecated swagger-cli package. This guide shows you how to replace the old commands with Redocly CLI commands. Redocly CLI is built for OpenAPI but you can assume that Swagger 2.0 is also supported when the documentation refers to an OpenAPI description. We know those existing APIs are still working hard in many places!
Modern API tooling
Redocly CLI lints your OpenAPI file, checking that it is valid and also making recommendations to improve your OpenAPI descriptions. While you have multiple options for using Redocly CLI for better API standards let’s start with replacing the old command with the new command for linting with the minimal ruleset.
If the old command was:
swagger-cli validate openapi.yml
Then the new command is:
redocly lint --extends=minimal openapi.yml
You can run these commands locally, as part of your CI (continuous integration) pipeline, or (ideally) both.
In some cases, the additional rules from linting won't be useful. For instance, in the case of legacy APIs that won't be updated to meet more modern API expectations. To restrict Redocly to only checking that the API description meets the expected structure for OpenAPI, use a
redocly.yaml file to configure a ruleset that contains only the
The configuration in the
redocly.yaml file should look like this:
extends:  rule: spec: error
Redocly CLI will automatically detect the configuration file, so your command should be:
redocly lint openapi.yml
You can add more built-in rules by adding them in the configuration file, and adjust the level of the messages by using
warn rather than
Learn more about configuring Redocly CLI in the documentation.
While the OpenAPI (and earlier Swagger) standards were designed to use
$ref reference syntax and re-use elements of API descriptions across mulitple files, not all tools support this. If there's a tool in your API lifecycle that needs a single file, you can still use mulitple files for the day-to-day work, and then "bundle" the API description into a single file for use by another tool.
swagger-cli the command would be something like this:
swagger-cli bundle openapi.yml
With Redocly CLI the command to create a single file is:
redocly bundle openapi.yml
Both commands have additional options; here's a quick reference on how to replace the old with the new:
--outputto direct the command output to a filename.
--extfor the file type to output. Redocly CLI also detects the correct format from the output filename, so this option isn't needed for file output, but can be useful if outputting to stdout.
--dereferencedto output a file with all
Redocly CLI has more functionality than
swagger-cli did, so if that sounds interesting you should visit the main docs and see if there's anything you'd like to add to your own workflows.