Skip to content
The Docs Report
Tuesday, November 17, 2026NewsletterRSS

Redocly CLI Can Now Apply Overlays When Bundling an API Description

Redocly CLI 2.56.0, released Sept. 30, applies OpenAPI Overlay documents to bundle output and lints Overlay 1.1 and 1.2. Version 2.57.0 tightens const checks.

2 min read

RedoclyOpenAPIAPI reference

Product photo of a white rubber stamp on a cherry red, orange and hot pink gradient

Redocly CLI can now apply Overlay documents to the output of its bundle command, according to the Redocly CLI changelog entry for version 2.56.0, released Sept. 30. Users pass overlays with a new --overlay option, or list them under overlays for an API in redocly.yaml.

Overlays move into the bundle step

An Overlay is a separate document that lists edits to apply to an OpenAPI description. The bundle command merges a multi-file API description into one file. With 2.56.0, the CLI applies the overlays to that output in the same run. A team can keep the overlay list in redocly.yaml next to the rest of its API configuration.

Linting covers Overlay 1.1 and 1.2

The same release added linting for Overlay 1.1 and 1.2 documents, including the copy action field, the $self field and reusable actions defined in components.actions. Redocly also extended its spec-ref-siblings rule so it checks the fields placed next to a reusable action’s $ref in an Overlay document.

A stricter const check followed the same day

Version 2.57.0, also released Sept. 30, added const checking to the no-enum-type-mismatch rule. A const value must now conform to its schema’s type, the same way every enum value already does. Redocly warned that linting output may show new errors for schemas whose const value doesn’t match their type. The release also fixed the rule dropping violations and reporting a wrong location when type was written as an array.

Other fixes in the week’s releases

Version 2.55.0, released Sept. 28, added a --replace option to the push command, which removes files under the mount path that aren’t part of the push. It also fixed respect, Redocly’s API workflow testing tool. It now masks known secrets in non-JSON request bodies such as application/x-www-form-urlencoded token requests. A step now fails with a clear error when a runtime expression embedded in a string has no value, such as Bearer {$outputs.accessToken}. Version 2.56.0 fixed an unexpected respect error when a step used an operationId without the $sourceDescriptions.<name>. prefix.

Key takeaways

  • redocly bundle accepts Overlay documents through --overlay or an overlays list in redocly.yaml.
  • The linter understands Overlay 1.1 and 1.2, including copy, $self and reusable actions.
  • Version 2.57.0 checks const values against their schema type, which can surface new lint errors.
  • redocly push --replace deletes remote files that aren’t in the push.

The take

We think the bundle change matters more than it looks. It moves overlays out of a side script and into the build everyone already runs. A script is easy to skip, and two builds can then disagree. When the bundle command applies the edits, everyone gets the same output from the same command. Check the const rule before upgrading: run the linter on a branch first, because a schema that passed last week can fail now. Teams that publish a public description and keep an internal one should try --overlay on a copy of their pipeline.