CLI Quick Start

Install the oasdiff command-line tool and detect breaking changes in under two minutes.

Install

Homebrew (macOS / Linux)

brew install oasdiff

curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

Docker

docker run --rm -v $(pwd):/specs tufin/oasdiff breaking /specs/base.yaml /specs/revision.yaml

Pre-built binaries

Download for Linux, macOS, or Windows from the GitHub releases page.

Your first diff

Run a breaking change check between two OpenAPI specs:

oasdiff breaking base.yaml revision.yaml

Exit code is 0 when there are no breaking changes, 1 when breaking changes are found. This makes it easy to fail a CI step automatically.

Output formats

Flag	Description
(default)	Human-readable text
--format json	Machine-readable JSON
--format yaml	YAML output
--format html	Annotated HTML report
--format markdown	Markdown, great for PR comments
--format githubactions	GitHub Actions annotations (::error::)

Other commands

oasdiff changelog base.yaml revision.yaml

All changes (breaking + non-breaking)

oasdiff diff base.yaml revision.yaml

Raw structural diff

oasdiff validate spec.yaml

Validate a single spec against OpenAPI and JSON Schema rules

Run oasdiff --help for every subcommand and flag, or see the full README on GitHub for the reference docs, the breaking-change rule catalogue, configuration-file syntax, and the public Go API.

Share a side-by-side review

Add --open to breaking or changelog to open a full side-by-side review of the two specs in your browser, with the diff anchored at each change. The comparison is encrypted on your machine before upload, so we never see your specs, and the resulting link works for 7 days, paste it into a PR or Slack and teammates can open it with no CLI install and no account.

oasdiff changelog HEAD~1:openapi.yaml HEAD:openapi.yaml --open

See how to use a review for sharing, single-change links, and opening a review from the GitHub Action.

Language support

Output breaking change messages in your team's language:

oasdiff breaking base.yaml revision.yaml --lang ru   # Russian
oasdiff breaking base.yaml revision.yaml --lang pt   # Portuguese (Brazil)
oasdiff breaking base.yaml revision.yaml --lang es   # Spanish

Next steps

Add to GitHub Actions →Browse all 450+ rules →