{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/commands/drift","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/commands/drift","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"drift","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"drift","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," command detects drift between recorded HTTP traffic and an OpenAPI description."," ","The command reads a traffic log (or a folder of logs), matches each request/response exchange to a documented operation, and reports the discrepancies it finds."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Experimental"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an experimental feature."," ","Its behavior, command, flags, and output may change in future releases."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," command supports OpenAPI 3.x descriptions only."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," command reports:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["undocumented endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["undocumented request parameters and headers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["missing required parameters or request bodies"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["request and response schema mismatches"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["baseline security issues (opt-in OWASP API risk heuristics)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spec loading reuses the same engine as the other commands (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/openapi-core"]},"), and schema validation reuses the bundled ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/ajv"]},", so there are no extra runtime dependencies."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-traffic-formats","__idx":1},"children":["Supported traffic formats"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The traffic input can be provided in any of the following formats."," ","By default the format is detected automatically from the file contents:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HAR"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Kong"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Nginx JSON"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apache JSON"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["NDJSON"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JSON-array traffic files (HAR, Kong, and webserver JSON) are read fully into memory."," ","For very large captures, prefer the NDJSON format, which is streamed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":2},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift <traffic> --api <api>\nredocly drift <traffic> --api <api> [--traffic-format=<option>]\nredocly drift <traffic> --api <api> [--format=<option>] [--output=<file>]\nredocly drift <traffic> --api <api> [--server=<url>]\nredocly drift <traffic> --api <api> [--match-mode=<option>]\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":3},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["traffic"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to a traffic log file or folder (HAR, Kong, Nginx/Apache JSON, NDJSON)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," OpenAPI description file or folder to validate against."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--traffic-format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Traffic input format.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["har"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kong"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nginx-json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apache-json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ndjson"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Output format.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pretty"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["csv"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sarif"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pretty"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--match-mode"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How requests are located via the description ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["servers"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strict-host"]}," also requires the host to match; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["basepath"]}," matches only the base path.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strict-host"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["basepath"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strict-host"]},". Mutually exclusive with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--server"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--server"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server URL the traffic was captured against (host, host + base path, or a path-only prefix like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api"]},"). Only requests under it are considered, and the rest of their URL is treated as the API path. Replaces the description ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["servers"]},". Mutually exclusive with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--match-mode"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ignore-cookies"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ignore cookie-based checks (useful for logs exported without cookies). Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ignore-headers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma-separated header names to skip in undocumented-header checks. A trailing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*"]}," matches by prefix, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-consumer-*"]},". Useful for headers a gateway or proxy adds that are not part of the API contract."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--max-findings"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum findings shown in pretty output. Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--min-severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Discard findings below this severity from the report (all formats).",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warning"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--rules"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma-separated subset of builtin rules to run: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undocumented-endpoint"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema-consistency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security-baseline"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owasp-api-top10"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--output, -o"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write the drift report (in the format selected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--format"]},") to this file instead of stdout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify path to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/configuration"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--lint-config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for the configuration file.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display version number."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owasp-api-top10"]}," rule is opt-in and only runs when included in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--rules"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validate-a-har-capture-against-a-single-description","__idx":5},"children":["Validate a HAR capture against a single description"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./traffic.har --api ./openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validate-a-folder-of-logs-against-a-folder-of-descriptions","__idx":6},"children":["Validate a folder of logs against a folder of descriptions"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./traffic-logs/ --api ./openapi/ --format json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declare-the-server-the-traffic-was-captured-against","__idx":7},"children":["Declare the server the traffic was captured against"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the captured traffic does not carry the documented host or base path (for example, behind a gateway that adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api"]},"), use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--server"]}," to declare the actual server."," ","Only requests under it are considered, and the remaining path is matched against the description paths directly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./traffic.har --api ./openapi.yaml --server localhost:9000\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ignore-headers-added-by-a-gateway-or-proxy","__idx":8},"children":["Ignore headers added by a gateway or proxy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A gateway such as Caddy often injects headers that are not part of the API contract (for example authentication or consumer-identity headers)."," ","Skip them so they don't show up as undocumented headers."," ","Use a trailing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*"]}," to match a family of headers by prefix:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./traffic.har --api ./openapi.yaml --ignore-headers \"x-caddy-auth-token,x-auth-intent,x-consumer-*\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"write-the-report-to-a-file","__idx":9},"children":["Write the report to a file"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./traffic.har --api ./openapi.yaml --format json -o ./drift-report.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exit-codes","__idx":10},"children":["Exit codes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]},": no error-level findings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]},": error-level drift detected."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-commands","__idx":11},"children":["Related commands"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/commands/proxy"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}]}," captures live HTTP traffic into a HAR file that can be replayed through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/commands/generate-spec"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-spec"]}]}," infers an OpenAPI description from the same traffic formats."]}]}]},"headings":[{"value":"drift","id":"drift","depth":1},{"value":"Supported traffic formats","id":"supported-traffic-formats","depth":2},{"value":"Usage","id":"usage","depth":2},{"value":"Options","id":"options","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Validate a HAR capture against a single description","id":"validate-a-har-capture-against-a-single-description","depth":3},{"value":"Validate a folder of logs against a folder of descriptions","id":"validate-a-folder-of-logs-against-a-folder-of-descriptions","depth":3},{"value":"Declare the server the traffic was captured against","id":"declare-the-server-the-traffic-was-captured-against","depth":3},{"value":"Ignore headers added by a gateway or proxy","id":"ignore-headers-added-by-a-gateway-or-proxy","depth":3},{"value":"Write the report to a file","id":"write-the-report-to-a-file","depth":3},{"value":"Exit codes","id":"exit-codes","depth":2},{"value":"Related commands","id":"related-commands","depth":2}],"frontmatter":{"seo":{"title":"drift"}},"lastModified":"2026-07-21T09:36:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/commands/drift","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}