New in Redocly CLI

-experimental

# Your API says one thing. Your docs say another.

Nobody notices, because nothing fails – until an SDK breaks in a customer's build.

The gap has a name: `drift`. `proxy` records what your API actually does. `drift` compares it against what your OpenAPI description claims.

[Catch your drift](/docs/cli/commands/drift) [Read the announcement](https://redocly.com/blog/catch-api-drift)

$`npm i -g @redocly/cli@latest`

5

traffic formats supported

4

built-in rule packs

0

lines of extra test code

1

exit code that fails the build

/ The problem

## Nothing warns you about drift. Your customers find it first.

Drift builds up one hotfix and one forgotten field at a time. Your linter cannot see it, because the linter only reads the description. Only the traffic shows what the API really does.

### Generated SDKs break

An SDK generated from a stale description compiles fine – then throws in production when the API returns a field the types do not declare.

### Partner integrations choke

A partner builds against a field that was "documented" but never actually returned. Their integration fails, and your support queue hears about it first.

### Shadow endpoints ship

Endpoints and parameters nobody documented run in production anyway – invisible to your security review, your gateway policies, and your API governance.

/ How it works

## Record first. Compare later.

Two commands, one plain HAR file between them. Use them together, or feed `drift` traffic you already have – browser DevTools exports, Kong, Nginx, or Apache logs.

redocly proxy

**Capture what your API actually does.** A local reverse proxy in front of your API. Point any client at it – a browser, a test suite, a curl script – and every exchange is captured into a standard HAR file.

- ✓Streams to disk as it captures – nothing held in memory
- ✓Validates live against your description with `--api`
- ✓Requests pass through unchanged

[proxy command reference](/docs/cli/commands/proxy)

redocly drift

**Compare it against what you claim.** Replays recorded traffic against your OpenAPI description, matches each exchange to a documented operation, and reports every discrepancy it finds.

- ✓Undocumented endpoints, parameters, and headers
- ✓Request and response schema mismatches
- ✓Reports as pretty text, JSON, CSV, or SARIF

[drift command reference](/docs/cli/commands/drift)

Your clients

tests · curl · browser

redocly proxy

records → capture.har

redocly drift

+ openapi.yaml

Drift report

exit code 1 on error

/ Two-minute demo

## Find real drift in two requests

No setup required – try it against [Redocly Cafe](https://cafe.redocly.com/openapi/cafe), our public demo API. Change one field in the description, and drift finds it, together with a problem you did not add.

1. 1
   ### Start a proxy in front of the live API
   One command, and every request that flows through `localhost:4040` is on the record.
2. 2
   ### Send some traffic through it
   Two curl requests are enough. Press `Ctrl+C` and the proxy writes the HAR file.
3. 3
   ### Break the description on purpose
   Change `page.total` from `integer` to `string` in the Cafe OpenAPI description. This is a typical silent drift.
4. 4
   ### Replay and read the report
   The error is the change you made in step 3. The warning – an undocumented `category` query parameter – is drift that was already there. Two requests were enough to find a real problem.

## Your e2e tests are already writing contract tests. Stop throwing them away.

Every test run sends realistic traffic to your API – and then discards it.

Start proxy before the run, route the tests through it, and replay the capture with drift when they finish.

128 requests capturedexit code 12 findings

The proxy sits between your tests and the API: requests pass through unchanged, and every exchange is captured on the way.

- ✓Every test run doubles as a contract check
- ✓Zero extra test code to write or maintain
- ✓Exit code 1 on error-level findings fails the pipeline
- ✓SARIF output plugs straight into code scanning

/ Built-in rules

## More than schemas

Findings come from four built-in rule packs. Run them all, or pick a subset with`--rules`

undocumented-endpoint

**Find the endpoints nobody wrote down.** Flags traffic that doesn't match any documented operation – the shadow API your governance never sees.

schema-consistency

**Validate every payload against its schema.** Validates parameters, headers, and request/response bodies against your schemas, powered by the same engine that lints your descriptions.

security-baseline

**Check that security requirements are enforced.** Checks that requests actually satisfy the security requirements your description declares, and flags credentials sent over plain HTTP. Loopback hosts are exempt, so local sandboxes stay warning-free.

owasp-api-top10opt-in

**Scan traffic with OWASP heuristics.** Looks for credential-like query parameters, insecure CORS, weak cookie attributes, sensitive-looking response fields, and large unpaginated responses – based on the OWASP API Security Top 10.

/ API coverage

## No findings? Check how much of your API the traffic reached

A drift report reflects only the traffic you send. Add `--coverage` to score that traffic against your full API description.

- ### Operations
  Every operation of the description. Covered when at least one exchange matched it.
- ### Parameters
  Every path, query, header, and cookie parameter. Covered when a matched exchange carried it.
- ### Schema properties
  Every property reachable from the JSON body schemas. Covered when a body carried the field.
- ### Response codes
  Every documented response, including ranges like 2XX. Covered when the API returned it.

### Find the gaps

Add `--coverage-output` to write a JSON report that lists the untested items in each operation, so you know which tests to write next.

[API coverage reference](/docs/cli/commands/drift#api-coverage)

$

redocly drift ./traffic.har --api ./openapi.yaml --coverage

Exchanges: total=128 documented=128 undocumented=0

Findings: total=0 error=0 warning=0 info=0

✓ No findings.

API coverage

operations91%11/12

parameters68%17/25

schema properties41%52/126

response codes57%16/28

{

"method": "GET",

"path": "/orders/{id}",

"missing": [

{ "kind": "parameter", "name": "expand" },

{ "kind": "response", "status": "404" },

{ "kind": "property",

"path": "items[].discount" }

]

}

/ Interoperability

## Works with the logs you already have

No agents to install, no vendor lock-in. If you have traffic, you can check it – and the report goes wherever your tooling lives.

Traffic in

HARKongNginx JSONApache JSONNDJSON (streamed)

redocly drift

Reports out

prettyJSONCSVSARIF

Experimental: both commands support OpenAPI 3.x descriptions only, and flags, output formats, and behavior may change – including breaking changes – while we shape them with your feedback.

> “Your API and its description should tell the same story. Now you can check.”
>
> The Redocly CLI team

## Frequently asked questions

No. The two commands meet at a plain HAR file, so either works alone. Traffic exported from browser DevTools, Kong, or Nginx/Apache JSON logs feeds drift directly – and if you prefer immediate feedback, proxy accepts an “--api” flag and validates traffic live, as it flows.

## Stop guessing. Start checking.

Two requests of traffic are enough to find a real problem.

[Read the full guide](/docs/cli/commands/drift) [Share feedback on GitHub](https://github.com/Redocly/redocly-cli/issues)

1

$`npm i -g @redocly/cli@latest`

[Redocly CLI install guide](/docs/cli/installation)

2

$`redocly proxy --target http://localhost:9000 --har capture.har`

[Proxy command docs](/docs/cli/commands/proxy)

3

$`redocly drift capture.har --api openapi.yaml`

[Drift command docs](/docs/cli/commands/drift)
