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.

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 →