This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent edits an API description, it needs a way to check that the file still follows the API’s rules. Redocly CLI is a command-line tool that reads API descriptions, reports rule violations, and can combine related files into one output. An API description is a structured file that defines endpoints, inputs, and responses.
An agent can run Redocly CLI in the project shell to check a changed OpenAPI description and get the results in JSON. Linting checks the description's syntax and configured rules. It does not send requests to the API. The commands below use a local file, require no Redocly account, and do not put credentials in the agent’s prompt.
Set up the CLI
Redocly CLI can lint OpenAPI descriptions. It also lints AsyncAPI event descriptions and Arazzo descriptions, which describe sequences of API calls. Its installation page describes a local install with npm. You can also run it with npx or Docker. Version 2 needs Node.js 22.12.0 or higher.
For a one-off run, use npx to fetch and run the package:
npx @redocly/cli@latest --help
This command may download the package if it is not already available locally, so it needs network access. Once the CLI is available, linting and bundling local files do not require a Redocly service login. A specification that refers to remote files is a separate case: resolving those references requires access to their URLs.
Redocly CLI also sends anonymized usage data when a command runs, such as the command name and its exit code. Set the REDOCLY_TELEMETRY environment variable to off if the agent's environment should not send it.
Lint a changed API description
For an OpenAPI description split across files, run lint on the main file that points to the others. Replace the placeholder path below with the actual file in the repository:
npx @redocly/cli@latest lint path/to/openapi.yaml --format=json
The lint command checks the description against the rules Redocly CLI is set to use. Without a redocly.yaml file that sets rules, it uses the built-in recommended ruleset. The --format=json option returns diagnostics in a format an agent can inspect or pass to a script. Without that option, lint prints its default codeframe format. Its ruleset templates describe built-in rule choices. The choices include minimal and recommended, along with recommended-strict.
If the command reports a problem, the agent should use the file and location in the diagnostic to make a focused edit, then run the same lint command again. The result confirms whether the edited description passes the configured checks. A clean lint result does not prove that a live API behaves as described; linting reads the contract and does not call the service.
A realistic prompt for this task is:
Check the OpenAPI description I changed. Run Redocly CLI lint with JSON output, fix only issues caused by my edits, and rerun lint. Do not change the API’s behavior or bundle the files. Report any remaining findings.
Bundle only when a single file is needed
Some tools need one self-contained OpenAPI file instead of a description split across files. Redocly CLI can create that file with bundle:
npx @redocly/cli@latest bundle path/to/openapi.yaml -o /tmp/openapi.bundle.yaml
Here, path/to/openapi.yaml is the project’s entry point, and /tmp/openapi.bundle.yaml is the output destination. The bundle command follows the $ref references from that root file and writes one output file. It does not replace the source files, but it overwrites an existing file at the output path. Run bundling separately from linting. That way, the agent does not create an output file when the task only asks for validation.
Know what the checks cover
A ruleset is the collection of checks Redocly CLI runs. A project’s redocly.yaml file can configure those checks, and custom JavaScript plugins can add checks that configurable rules cannot express. An agent should inspect the repository’s existing configuration before changing rules; otherwise, it could make lint pass by weakening the project’s checks.
Redocly CLI also has a skills command that installs Redocly's agent skills into the project. These are instructions that teach coding agents how to work with the CLI. The skills ship inside the CLI and match the installed version. They are optional: an agent can run the CLI commands directly when it has shell access.