Command arguments

Shared inputs and flags for every openapi-changes command.

openapi-changes exposes seven commands:

The five comparison/reporting commands all use the same doctor-based comparison engine and accept the same input shapes. The utility commands are different:

  • completion generates shell completion scripts
  • version prints the raw build version string

Supported input modes

Local git repository history

If the OpenAPI spec lives in a local git repository, pass two arguments:

  • the path to the git repository
  • the path to the OpenAPI spec inside the repository

If the full path to a spec is /home/pb33f/corp-code/specs/v3/openapi.yaml, the arguments would be:

  • repository path: /home/pb33f/corp-code
  • file path: specs/v3/openapi.yaml

Examples:

openapi-changes console ./ specs/v3/openapi.yaml openapi-changes summary /home/pb33f/corp-code specs/v3/openapi.yaml

GitHub file history

If the spec is hosted on GitHub, pass a single argument: the GitHub URL to the file.

Examples:

openapi-changes html-report https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml openapi-changes summary https://github.com/stripe/openapi/blob/master/openapi/spec3.json

Left and right file comparison

If you have two standalone OpenAPI files and no git history, pass both file paths directly. The first file is the original, and the second file is the modified version.

Examples:

openapi-changes report old-spec.json new-spec.json openapi-changes markdown-report /home/pb33f/corp-code/old-spec.json /home/pb33f/corp-code/new-spec.json

Git revision comparison

Compare a file at different git revisions using the revision:path syntax. The revision can be any git ref: a branch name, tag, HEAD~N, or commit SHA. The path is relative to the repository root.

You can mix revision inputs with local files or URLs. The first argument is the original and the second is the modified version.

Examples:

openapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml openapi-changes html-report main:api/openapi.yaml feature-branch:api/openapi.yaml openapi-changes report v1.0.0:specs/openapi.yaml ./specs/openapi.yaml

Multi-file specs with $ref references are fully supported. When a revision input is used, external references are resolved from the same git revision, not from the working tree.

Resolving external references

If your spec contains unresolved external $ref values, use --base / -p to tell openapi-changes where to resolve relative or remote references from.

Local example:

openapi-changes summary -p . sample-specs/petstorev3.json

Remote example:

openapi-changes summary -p https://somewhere.megacorp.com sample-specs/petstorev3.json

Global flags

These flags apply to the five comparison commands: console, summary, report, markdown-report, and html-report.

Flag Short Description
--base -p Base URL or working directory to use for relative and remote references
--base-commit Commit to compare against when walking history
--config -c Path to a breaking-rules config file
--ext-refs Resolve $ref values inside extension (x-) objects
--global-revisions -R Consider all revisions in the limit window, not just revisions that touched the file
--limit -l Limit the number of revisions inspected
--limit-time -d Limit history by days instead of revision count
--no-logo -b Skip the startup banner
--remote -r Allow remote references to resolve automatically without --base
--top -t Only compare the latest revision against HEAD

--no-logo is useful for CI, pull request comments, and other automation where the banner would add noise to captured output.

Example:

openapi-changes summary -t ./ sample-specs/petstorev3.json

Terminal themes

The terminal-facing commands also expose alternate terminal themes:

Flag Description
--no-color, -n Use the light Roger monochrome terminal theme
--roger-mode Alias for --no-color
--tektronix Use the Tektronix green monochrome terminal theme

These flags are available on console, summary, report, markdown-report, and html-report.

Command-specific flags

Some commands add their own flags on top of the shared set:

  • Summary: --markdown, --error-on-diff, --with-lines
  • Report: --reproducible
  • Markdown Report: --include-diff, --report-file
  • HTML Report: --no-explorer, --report-file
  • Completion: shell-specific subcommands such as bash, zsh, fish, and powershell
  • Version: no flags; prints only the raw version string

If you want to customize breaking rules, see Configuring.