redocly lint: Validate OpenAPI Definitions
redocly lint checks an OpenAPI file against rules from redocly.yaml and exits non-zero when it finds errors.
Redocly CLI bundles a fast OpenAPI linter with configurable rulesets and presets. It is a common alternative to Spectral, especially when you already build docs with Redocly.
What it does
redocly lint resolves an OpenAPI 2.0/3.0/3.1 description (following $refs), applies the ruleset from redocly.yaml (or a preset), and prints problems as errors or warnings. It exits non-zero if any error-severity problem is present.
Common usage
redocly lint openapi.yaml
# lint an API declared in redocly.yaml by name
redocly lint core@v1
# CI-friendly output
redocly lint --format=github-actions openapi.yamlOptions
| Flag | What it does |
|---|---|
| --config <file> | Path to redocly.yaml |
| --format <fmt> | stylish, codeframe, json, checkstyle, github-actions |
| --max-problems <n> | Cap how many problems are printed (default 100) |
| --generate-ignore-file | Write a .redocly.lint-ignore.yaml baseline |
| --skip-rule <name> | Turn off a specific rule for this run |
| --extends <ruleset> | Apply a preset: recommended, minimal, spec |
In CI
Use --format=github-actions so failures annotate the PR diff inline. To adopt linting on a legacy spec, run redocly lint --generate-ignore-file once to baseline existing problems, commit the ignore file, and let the gate catch only new violations.
Common errors in CI
On failure the tail reads ❌ Validation failed with N errors and M warnings. (older builds print Errors found) and the exit code is non-zero. "Something went wrong when processing ... Cannot resolve $ref" means a broken reference. "The config file needs to be updated" appears when redocly.yaml uses an old schema; run redocly with the current version. "No configuration file found" is safe (defaults apply) unless you expected custom rules.