Migrate to Redocly CLI v2.x from v1.x

Redocly CLI v2 introduces improved architecture and removes deprecated features to make the tool easier to maintain and extend. This guide covers the essential changes you need to make when upgrading from v1.x.

Node.js version: Update to Node.js 20.19.0+, 22.12.0+, or later.

The codebase has been rewritten from CommonJS to ES Modules. This affects plugins: update your plugin syntax to use ES Modules, or use the .cjs extension for CommonJS files.

The only default configuration file name is now redocly.yaml. If you still use the legacy .redocly.yaml, please rename it. You can still use a different file name, but you must explicitly specify it with the --config flag.

Several deprecated configuration options have been removed:

# ❌ Removed - use 'apis' instead
apiDefinitions:
  - openapi.yaml

# ✅ Use this instead
apis:
  main:
    root: ./openapi.yaml

# ❌ Removed - use 'openapi' directly
features.openapi:
  theme:
    colors:
      primary:
        main: '#ff0000'

# ❌ Removed - use 'openapi' directly
theme:
  openapi:
    theme:
      colors:
        primary:
          main: '#ff0000'

# ✅ Use this instead
openapi:
  theme:
    colors:
      primary:
        main: '#ff0000'

# ❌ Removed - use 'rule/' prefix
rules:
  assert/name: error

# ✅ Use this instead
rules:
  rule/name: error

The spec rule has been replaced with struct:

# ❌ Removed
rules:
  spec: error

# ✅ Use this instead
rules:
  struct: error

Or use the new spec ruleset for specification compliance:

extends:
  - spec

Removed rule path-excludes-patterns. Use a configurable rule instead. You may refer to this Cookbook recipe.

Removed rule info-license-url. Use info-license-strict which better complies with the new OpenAPI 3.1 specification.

The undefined assertion has been removed:

# ❌ Removed
rules:
  rule/check-property:
    subject:
      type: Operation
      property: summary
    assertions:
      undefined: false

# ✅ Use this instead
rules:
  rule/check-property:
    subject:
      type: Operation
      property: summary
    assertions:
      defined: true

The join command no longer merges servers into the root level. Each path item now retains the servers from its source description, so that joined descriptions remain unmodified. This fixes incorrect behavior but may break workflows that relied on root-level server inheritance.

To restore root-level servers, use a custom decorator like the following:

export default function plugin() {
  return {
    id: 'my-plugin',
    decorators: {
      oas3: {
        'add-servers': () => ({
          Root: {
            leave: (root) => {
              root.servers = [{ url: 'https://your-server-url.com' }];
            },
          },
        }),
      },
    },
  };
}

Register the plugin in redocly.yaml and run join followed by bundle to apply it:

redocly join foo.yaml bar.yaml -o tmp.yaml
redocly bundle tmp.yaml -o joined.yaml

Since v2.0, Redocly CLI uses the latest specification when parsing YAML files (v1.2 at this time). This update changes how some YAML features are interpreted compared to v1.x:

• Numbers with underscores are treated as strings (e.g. 3_14 is treated literally as a string instead of 314).

• Indentation requirements are stricter for mixed YAML and JSON content. Everything related to a property must be indented, including the closing brace:

  foo: {
    bar: something
  }
    }
  baz: something else
  

The build-docs command renders documentation with Redoc 3 instead of Redoc 2. Redoc options come from the configuration key that matches your API description type: openapi, asyncapi, or graphql. The --theme.openapi option has been removed:

# ❌ Removed
redocly build-docs openapi.yaml --theme.openapi.hideDownloadButtons

# ✅ Use this instead
redocly build-docs openapi.yaml --openapi.hideDownloadButtons

The --disableGoogleFont option has been removed too, because Redoc 3 pages load no Google Fonts.

Redoc 3 renamed or removed some Redoc 2 options and replaced the theme object with CSS custom properties, so review your settings against the Redoc configuration options and check your custom templates. Read what's new in Redoc 3 for details.

To keep the Redoc 2 output, pin @redocly/cli to the version you used before, or use Redocly CLI v1: npx @redocly/cli@v1-archive build-docs openapi.yaml.

When two referenced components share a name but have different content, the bundle command renames one of them. Redocly CLI v1 prefixed the file name to the component name. Since v2.27.1, bundle adds a numeric suffix instead.

For example, the root document defines an Order schema and references a different Order from another file:

# openapi.yaml
paths:
  /orders:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./schemas.yaml#/Order
components:
  schemas:
    Order:
      type: object

# schemas.yaml
Order:
  type: object
  properties:
    coffee:
      type: string

In the bundled output, Redocly CLI v1 names the second schema schemas_Order, and v2 names it Order-2:

components:
  schemas:
    Order:
      type: object
    schemas_Order: # Order-2 in v2
      type: object
      properties:
        coffee:
          type: string

The change applies to every component type and changes the $ref paths in the bundled output. To control the names, see Configure the component names strategy and Configure component renaming conflicts.

• Legacy Registry: Support for the legacy Redocly API Registry has been removed in favor of Redocly platform.
• Commands: The preview-docs command has been removed - use preview instead.
• Labels: The labels field in the apis section has been removed.

A new spec ruleset is available that enforces OpenAPI specification compliance:

extends:
  - spec

The no-duplicated-tag-names rule checks for duplicate tag names in your API description.

Now Redocly CLI supports JSON schema formats:

openapi: 3.1.0
paths:
  /users/{id}:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
              examples:
                Correct:
                  value:
                    email: correct@email.com
                Incorrect:
                  value:
                    email: wrong-email # Will fail validation

1. Update Node.js to a supported version (20.19.0+, 22.12.0+, or 23+).
2. Rename configuration file name to redocly.yaml (if it differs).
3. Replace spec rule with struct.
4. Update configurable rules to use rule/ prefix instead of assert/.
5. Replace undefined assertions with defined: true.
6. Revise join command usage if your workflow relies on root-level servers in joined output.
7. Revise your YAML files to comply with the latest YAML specification (v1.2).
8. Revise build-docs usage: replace --theme.openapi with --openapi, remove --disableGoogleFont, review your Redoc options and custom templates for Redoc 3, or pin the CLI version to keep the Redoc 2 output.
9. Update configuration structure:
   • Replace apiDefinitions with apis
   • Move features.openapi.* to openapi.*
   • Remove labels from apis section
10. Update plugins to ES Modules syntax or use .cjs extension.
11. Test your configuration with redocly check-config.

• Explore the changelog for detailed information about all changes.
• Check out the v2 documentation.