Migrating from Optic to oasdiff

Optic's team joined Atlassian and the open-source CLI is archived. If you used Optic to catch breaking changes in CI, oasdiff covers that job. This page maps each Optic workflow to its oasdiff equivalent, and is honest about what doesn't map.

Command equivalents

Optic	oasdiff
`optic diff openapi.yml --base main`	`oasdiff changelog main:openapi.yml openapi.yml`
`optic diff a.yml b.yml`	`oasdiff changelog a.yml b.yml`
`optic diff <url1> <url2>`	`oasdiff changelog <url1> <url2>`
`optic diff --check`	`oasdiff breaking --fail-on ERR`
`optic diff --web`	`oasdiff changelog --open`
`exclude_operations_with_extension: x-draft`	`--filter-extension x-draft`, or `x-stability-level: draft` on the operation
`severity: warn` on a ruleset in `optic.yml`	`--severity-levels` file, per check
examples-match-schema ruleset	`oasdiff validate` (reports example/schema mismatches)

Notes on the mappings:

changelog vs breaking: oasdiff changelog lists every change, classified as error, warning, or informational, which matches what optic diff printed. oasdiff breaking is the same report restricted to errors and warnings, so it is the one to use as a CI gate.
Git-based comparison works the same way: main:openapi.yml reads the file from a branch, tag, or commit, so the CI pattern "compare my branch to main" is one command with no checkout gymnastics. See Getting started.
Severity is per rule, not binary. Optic's breaking-changes ruleset fails or passes; oasdiff classifies every change as error, warning, or informational across 506 documented checks, and --fail-on decides what gates the build. Request/response direction is taken into account: the same edit can be breaking on a request and harmless on a response.
Tuning rules: Optic set severity per ruleset in optic.yml; oasdiff's --severity-levels file is finer-grained, setting any individual check to err, warn, info, or none (disabled). See Customizing severity levels.
Waving through one specific change (rather than tuning a rule): --err-ignore and --warn-ignore take a file of patterns matching individual findings, so a known, accepted breaking change stops failing CI while the rule stays active everywhere else. See Ignoring specific breaking changes. In oasdiff Pro this is a reviewer clicking approve on the change in the PR, with no ignore file to maintain.
Work-in-progress endpoints: Optic skipped operations marked with a custom extension like x-draft. The drop-in equivalent, with no spec changes, is --filter-extension x-draft, which excludes paths and operations carrying a matching extension. Longer term, prefer the built-in mechanism: mark an operation x-stability-level: draft (or alpha) and it is excluded from breaking-change detection by default, no flag needed; beta and stable endpoints are checked, and changing an endpoint's level is itself detected. See API stability levels.
Visual review: Optic's --web opened a local changelog page; --open opens a shareable side-by-side review of the change. The comparison is encrypted on your machine and the server stores only ciphertext, so it works for private specs; links expire after 7 days.
Major-version bumps: Optic allowed all breaking changes when info.version jumped a major. oasdiff has no version-aware bypass yet; teams that want this behavior skip the breaking step on major-bump PRs in their workflow, keeping the policy visible in CI config rather than implicit. If you want it built in, upvote issue #1007.

CI: the equivalent GitHub Action

The common Optic CI job, fail the PR on breaking changes against main, becomes:

- uses: oasdiff/oasdiff-action/breaking@v0
  with:
    base: main:openapi.yml
    revision: openapi.yml

The GitHub Action guide covers the rest: inline annotations, the PR review comment, and configuring the action with .oasdiff.yaml.

What doesn't map

Optic did three things beyond breaking-change detection. Two of them oasdiff deliberately doesn't do, and one it covers differently:

Capture (tests-to-spec): generating and patching OpenAPI from test traffic has no oasdiff equivalent. The archived Optic CLI still installs from npm and its capture mode keeps working offline; some teams keep it for capture and use oasdiff for the CI gate.
Style linting (naming conventions, required descriptions, Spectral orchestration): oasdiff is not a style linter. Spectral runs standalone and covers this; note that Optic's "forwards-only" mode (new rules applied only to new endpoints) has no direct replacement, so decide per rule whether it applies to existing endpoints.
Spec validity: where Optic bundled lint rules, oasdiff validate checks a single spec for per-RFC violations plus a small set of native lints (duplicate enum values, ambiguous parameter serialization, example/schema mismatches). It is validation, not style enforcement.

What Optic didn't have

A few things you gain in the move, beyond the per-rule severity model above:

Composed mode: diff a whole directory of specs with a glob (--composed "specs/*.yaml"), so a microservices repo with one spec per service is a single CI step instead of a loop. See Microservice APIs.
Machine-readable output: the changelog renders as YAML, JSON, Markdown, or HTML, and oasdiff diff emits the raw structural diff between two specs, so you can feed changes into release notes, dashboards, or your own tooling.
A review you can share: Optic's --web wrote a local HTML file, so showing a change to a teammate meant sending the file. --open produces a link anyone can open, and it is safe to use with private specs: the specs are encrypted on your machine, the server stores only ciphertext, and the decryption key stays in the URL fragment, which browsers never send to the server. See Free API change review.

Both tools resolve $refs and support specs split across multiple files, and both support OpenAPI 3.0 and 3.1, so specs need no changes to migrate the CI gate.