Free Open-Source CLI Tools for API Design

API design happens in your spec file long before any code ships. A style rule you forget, a breaking change you miss, a schema that drifts from what you shipped last week; all of it costs more to fix after the fact. The command line catches these problems where they start, and it does it in CI without anyone clicking through a UI.

This piece is about the open-source side of that toolchain. Every tool here is source-available under a permissive license, free to run with no seat cost, and something you can self-host or pin to a version you control. That matters when your API design lives in a Git repo and you want the checks to run the same way on every laptop and every pipeline. If you want the wider picture of how these fit together, start with our guide on how to design an API, then come back here to pick the CLIs.

You will get six tools, each with a real install command and the one command that shows it working: a linter for style rules, a fast Go-based alternative to it, a bundler that also validates, a code and doc generator, and two tools for catching breaking changes between spec versions. The OpenAPI Specification is the common language all of them speak, so a spec you lint with one tool feeds cleanly into the next.

One honest note up front. Apidog is featured here, but it is not open source; it is a commercial product with a free tier, and it does not lint your spec. So it gets an accurate aside, not an open-source entry. The tools below are the real open-source design toolchain.

What makes a CLI tool open source for API design

Open source is a specific claim, not a vibe. For this list, a tool qualifies when three things are true.

First, the license. It has to be a real permissive or copyleft license you can read; MIT and Apache-2.0 are the two you will see most here. That is what lets you use the tool in a commercial project without a license fee or a seat count.

Second, self-hosting and version control. You can vendor the binary, pin an exact version, and run it fully offline in an air-gapped CI runner. No tool here phones home or needs an account to do its core job.

Third, maintenance and community. A repo with recent commits, open issues that get answers, and a public changelog. An abandoned project can still be MIT-licensed and still be a bad bet, so I flag maintenance status where it matters.

Every tool below is checked against those three. Where a project is coasting, you will see it called out.

Spectral: the flexible OpenAPI style linter

Spectral from Stoplight is the reference open-source linter for API descriptions, licensed under Apache-2.0. It reads a ruleset (a YAML, JSON, or JavaScript file listing your rules) and applies it to OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, and Arazzo documents. If your team has a written API style guide, Spectral is how you make it executable.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Out of the box it ships an oas ruleset that flags missing descriptions, invalid examples, and structural problems. The real value shows up in custom rules: require an operationId on every operation, a shared schema on error responses, a naming convention on paths. Those rules live in your repo and run identically for every contributor.

Best at: enforcing a team style guide as code. Honest limit: Spectral checks a single spec; it does not compare two versions, so pair it with a diff tool to catch breaking changes.

vacuum: the fastest linter, drop-in for Spectral rulesets

If Spectral is the standard, vacuum is the speed play. It is a Go linter, MIT-licensed, that is 100% compatible with Spectral rulesets. So you can point it at the same ruleset you already wrote and get results back much faster on large specs, which is exactly what you want in a pre-commit hook or a tight CI loop.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

The -d flag gives you detailed per-rule output. vacuum also does more than lint; it generates HTML reports and documentation from the same spec. Because it is a single compiled binary with no Node runtime, it starts fast and drops cleanly into a container.

Best at: linting large specs quickly with rulesets you already have. Honest limit: the ruleset ecosystem and docs still center on Spectral, so you are often writing rules against Spectral’s model and running them through vacuum. That is a feature, but it means Spectral is still the thing you learn first.

Redocly CLI: lint plus bundle in one binary

Redocly CLI is MIT-licensed and covers a slightly different job. It lints, but its standout is bundle: it takes a spec split across many $ref files (the sane way to keep a large API design maintainable) and flattens it into one document for tools that expect a single file. It also generates API reference docs from the bundled result.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

Splitting your spec into per-resource files keeps diffs readable and merge conflicts small, which is core to a Git-native API design workflow. Redocly’s bundle is the step that turns that multi-file source back into the single artifact your CI, mock server, or doc site consumes.

Best at: multi-file spec projects that need bundling plus a validation pass. Honest limit: its default lint rules are lighter than a full custom Spectral ruleset, so many teams run Redocly for bundling and Spectral or vacuum for deep style enforcement.

openapi-generator: turn the design into clients, stubs, and docs

Design is not finished until other people can build against it. openapi-generator is Apache-2.0 and generates client SDKs, server stubs, and documentation from an OpenAPI spec across dozens of languages. Treating the spec as the source of truth and generating the rest is the heart of a schema-first, contract-driven approach, which we cover in API design principles.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Swap -g typescript-axios for go, python, java, kotlin, or any of the many supported generators. Run it in CI on every spec change and your client libraries never drift from the contract.

Best at: keeping generated code and docs in lockstep with the design. Honest limit: it needs a JDK to run (JDK 11+), the generated code is a starting point you will often customize, and generator quality varies by language target. Check the output before you ship it.

oasdiff: catch breaking changes before they reach clients

A linter tells you if one spec is clean. It cannot tell you that renaming a field just broke every client in production. oasdiff is the Apache-2.0 Go tool that fills that gap: give it two versions of a spec and it reports the diff, and specifically the breaking changes.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

The breaking command surfaces only the changes that break existing consumers; changelog gives a human-readable list of everything that shifted, breaking or not; diff gives the full machine-readable delta. Wire oasdiff breaking into a pull-request check and a breaking change becomes a failed build instead of a 3 a.m. page.

Best at: gating breaking changes in CI. Honest limit: it compares specs, so it is only as good as your discipline in keeping the spec current with the real API. It does not lint style; use it alongside Spectral or vacuum.

Optic: diff and lint together, with a maintenance caveat

Optic is MIT-licensed and does something the others split apart: it lints and diffs OpenAPI in one tool, comparing two versions to flag breaking changes while also applying style rules. It could even generate a spec from observed test traffic.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

Here is the honesty an open-source list owes you: Optic’s public repository was archived in early 2026 and the project is no longer actively maintained. The MIT source still runs, so you can vendor it, but you will not get new rules or security patches. For breaking-change detection today, oasdiff is the maintained option; Optic stays on the list because you will still meet it in existing pipelines.

Best at: teams already invested in it, or anyone who wants lint and diff in one CLI. Honest limit: no longer maintained as of early 2026; treat it as legacy and plan a migration path.

Where Apidog fits (and where it does not)

Apidog is not open source, and it does not lint your OpenAPI or enforce style rules; Spectral, vacuum, and Redocly are your linters, full stop. What Apidog offers is a different tradeoff: instead of stitching six separate binaries together, its free tier plus the apidog-cli binary gives you an integrated place to design endpoints and data schemas, then export the result as OpenAPI to feed right back into these open-source checks.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

The CLI has command groups for endpoint, schema, mock, and import/export, so you can script API design from the terminal and hand the exported spec to openapi-generator or oasdiff. See the complete Apidog CLI guide for the full command set. The honest framing: Apidog is the commercial, integrated option that plays nicely with the open-source toolchain, not a replacement for a linter and not an open-source project itself.

How to choose

Match the tool to the job. Most teams run two or three of these together, not one.

A practical stack: Spectral or vacuum for style, Redocly for bundling, oasdiff for breaking changes, and openapi-generator to produce clients. If maintaining that many tools is more than you want to own, an integrated platform covers the design-and-export part in one place. For a broader look at the tooling landscape beyond the CLI, see our guide to Swagger alternatives for API design and testing and the fundamentals in how to design REST APIs.

Wrapping up

The open-source CLI toolchain for API design is mature and free to run: Spectral and vacuum lint, Redocly bundles, openapi-generator produces clients, and oasdiff guards against breaking changes, with Optic as a legacy option to recognize. Wire them into CI and your API contract gets checked on every push with no per-seat cost and no vendor lock-in.

If you would rather design endpoints and schemas in one integrated tool and export clean OpenAPI into that same pipeline, Download Apidog and try the apidog-cli; it is the commercial companion to the open-source stack, not a replacement for your linter. Either way, the goal is the same: catch design problems in the terminal, before they reach your users.