redocly build-docs: OpenAPI Reference HTML
redocly build-docs openapi.yaml produces a single self-contained HTML API reference from an OpenAPI description, replacing the older redoc-cli.
Redocly builds Redoc-style API reference pages from OpenAPI. redocly lint validates the spec and redocly build-docs renders it; both belong in an API pipeline.
What it does
redocly build-docs reads an OpenAPI 2.0/3.x description, bundles its references, and outputs a static HTML API reference (default redoc-static.html). redocly lint checks the spec against a ruleset and exits non-zero on errors. This CLI supersedes the deprecated redoc-cli build.
Common usage
# lint the spec, then render docs
redocly lint openapi.yaml
redocly build-docs openapi.yaml -o docs/api.html
# the legacy command still seen in older pipelines
npx redoc-cli build openapi.yaml -o docs/api.htmlOptions
| Command / flag | What it does |
|---|---|
| redocly lint <spec> | Validate the OpenAPI description |
| build-docs <spec> -o <file> | Render a static HTML reference |
| --theme.openapi.<opt> | Theme options for the reference page |
| redocly bundle <spec> | Resolve $refs into one file |
| --config <file> | Use a redocly.yaml config |
In CI
Run redocly lint as a gate before redocly build-docs, so a malformed spec fails fast. Pin the @redocly/cli version. If you still call redoc-cli, migrate: it is deprecated in favor of redocly build-docs. Deploy the single HTML file like any static asset.
Common errors in CI
Error: Cannot find operationId ... or a lint summary ending ❌ Validation failed with N errors fails the pipeline; fix the flagged lines. We can't find a valid path to the OpenAPI definition means the spec path is wrong. Command "build" not found means you are on modern @redocly/cli where it is build-docs, not the old redoc-cli build.