{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migrate-to-redocly-cli-from-redoc-cli","__idx":0},"children":["Migrate to Redocly CLI from redoc-cli"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide shows how to replace old ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli"]}," commands with the updated Redocly CLI equivalents. We strongly recommend that all users upgrade as soon as they can."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prepare-the-tools","__idx":1},"children":["Prepare the tools"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Visit the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/installation"},"children":["installation page"]}," to find and use an installation method that works for you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Install ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly"]}," as a command (recommended, and used in the other examples in this article)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx"]}," to run the command without installing the package"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docker"]}," to run the command"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"replace-old-commands-with-new-ones","__idx":2},"children":["Replace old commands with new ones"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All Redocly CLI commands use a common configuration file. For theme options, linting rules, and other configuration, check out the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/configuration"},"children":["configuration documentation"]}," for all the details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"preview-documentation-locally","__idx":3},"children":["Preview documentation locally"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace the old ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli serve"]}," with:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly preview-docs --use-community-edition openapi.yaml\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The documentation output updates when the API description changes."," ","By default the documentation is available on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://127.0.0.1:8080"]}," but you can configure the host and port."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--use-community-edition"]}," parameter is needed for the tool to use Redoc to generate the docs; otherwise it generates the preview for our hosted ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/reference/"},"children":["API reference docs"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Command reference"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Visit the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/commands/preview-docs"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preview-docs"]}," documentation"]}," for more information and examples"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"publish-documentation","__idx":4},"children":["Publish documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli build"]}," commands with:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly build-docs openapi.yaml\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This generates a zero-dependency HTML file with your docs in, named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-static.html"]}," by default."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bundle-openapi-description","__idx":5},"children":["Bundle OpenAPI description"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have your OpenAPI description split between multiple files, replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli bundle"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly bundle"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi.yaml -o all-in-one.yaml\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Command reference"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Details and examples of using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," are on the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/commands/bundle"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command page"]},". Learn more about bundling, dereferencing, and handling unused components."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-configuration-settings","__idx":6},"children":["Update configuration settings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some of the configuration options have been updated. This section shows how to check which of your settings should be changed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"renamed-fields","__idx":7},"children":["Renamed fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two of the configuration settings were renamed for consistency with the rest of the Redocly tools."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menu"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebar"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codeSample"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codeBlock"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In both cases, the child options should work as before."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-command-line-configuration","__idx":8},"children":["Update command-line configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace your existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--options.theme.*"]}," settings with a new prefix: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--theme.options.theme.*"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example if you used ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli build --options.theme.sidebar.width='300px' openapi.yaml"]}," then the new command would be:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly build-docs --theme.openapi.theme.sidebar.width='300px' openapi.yaml\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-configuration-file","__idx":9},"children":["Update configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configuration belongs in a file named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},", or in a file name specified with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--config"]}," command-line parameter. You can read more about the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/configuration"},"children":["configuration file structure"]}," in the documentation, and changes between this and older versions are listed here."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Options named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["features.openapi.*"]}," should be re-prefixed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"theme:\n  openapi:\n    theme:\n      colors:\n        primary:\n          main: '#ff00ff'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define the base customization; older versions of the tools defaulted to using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]},", but this is no longer assumed. Set it in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"extends:\n  - recommended\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps-with-redocly-cli","__idx":10},"children":["Next steps with Redocly CLI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The newer tool has a lot more functionality than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli"]}," had, so explore the rest of the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1"},"children":["Redocly CLI documentation"]}," to find out more about:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensuring API quality with linting"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Managing large OpenAPI files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enhancing an OpenAPI description with decorators"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Uninstall"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend you uninstall ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-cli"]}," now that it is no longer needed."]}]}]},"frontmatter":{},"tagList":["admonition"],"title":"Migrate to Redocly CLI from redoc-cli","lastModified":"2025-05-28T16:01:32.000Z"}