Installation & Quick Start

Get oasdiff running 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 diff base.yaml revision.yaml --format html

Visual HTML report

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 300+ rules →Try the web tool →