DEV Community

Cover image for Free Open-Source CLI Tools for API Design
Hassann
Hassann

Posted on • Originally published at apidog.com

Free Open-Source CLI Tools for API Design

API design starts in your spec file, long before code ships. A missed style rule, breaking change, or schema drift is much cheaper to fix in a pull request than after release. CLI tools let you validate OpenAPI definitions locally and in CI without relying on a UI.

Try Apidog today

This post focuses on the open-source toolchain: tools with permissive licenses, no per-seat cost, and versions you can pin in your repository or CI environment. They all work with the OpenAPI Specification, so you can lint, bundle, generate, and diff the same contract. For the broader workflow, see how to design an API.

You will use six tools:

  • Spectral for style-guide linting
  • vacuum for fast Spectral-compatible linting
  • Redocly CLI for validation and bundling
  • openapi-generator for SDKs, stubs, and docs
  • oasdiff for breaking-change detection
  • Optic for legacy lint-and-diff pipelines

Apidog is included as a separate aside. It is not open source and does not lint OpenAPI specs, so it is not part of the open-source linter stack.

What qualifies as open source for API design?

For this list, a tool must meet three requirements:

  1. A real open-source license

    Each project uses a license you can inspect, such as MIT or Apache-2.0.

  2. Self-hosted, reproducible execution

    You can pin a version, run it locally or in CI, and use it without an account for its core functionality.

  3. Active or clearly documented maintenance status

    A permissive license is not enough if a project is abandoned. Where maintenance matters, it is called out below.

Spectral: enforce your API style guide

Spectral is an Apache-2.0 OpenAPI linter from Stoplight. It validates OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, and Arazzo documents using YAML, JSON, or JavaScript rulesets.

Install and run it:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Start with the built-in OpenAPI ruleset:

# .spectral.yaml
extends:
  - spectral:oas
Enter fullscreen mode Exit fullscreen mode

Then add rules that reflect your team’s API standards. For example, require every operation to have an operationId:

# .spectral.yaml
extends:
  - spectral:oas

rules:
  require-operation-id:
    description: Every operation must define an operationId
    given: $.paths[*][get,post,put,patch,delete,options,head]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Run the ruleset explicitly in CI:

spectral lint openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Best for: turning a written API style guide into checks that run on every machine and every pull request.

Limit: Spectral validates one spec at a time. Use a diff tool such as oasdiff to detect compatibility breaks between versions.

vacuum: fast linting with Spectral-compatible rulesets

If you already use Spectral rules, vacuum is a fast, MIT-licensed Go alternative. It is compatible with Spectral rulesets, which makes it useful for large specs, pre-commit hooks, and fast CI feedback.

Install and run it:

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Use the same ruleset you created for Spectral:

vacuum lint -d openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

The -d flag provides detailed per-rule output. vacuum can also generate HTML reports and documentation from the same API definition.

Because vacuum is a compiled binary, it avoids requiring a Node.js runtime in your CI image.

Best for: fast linting of large OpenAPI documents with existing Spectral rulesets.

Limit: Most ruleset examples and documentation are still centered on Spectral, so Spectral is usually the rules model you learn first.

Redocly CLI: validate and bundle multi-file specs

Redocly CLI is MIT-licensed and handles two common jobs:

  • Linting and validation
  • Bundling multi-file OpenAPI specs into one artifact

Install it:

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Validate a spec:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bundle a spec with external $ref files:

redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

For example, keep resource definitions separate during development:

openapi.yaml
paths/
  users.yaml
components/
  schemas/
    user.yaml
    error.yaml
Enter fullscreen mode Exit fullscreen mode

Then produce a single file for downstream tools:

redocly bundle openapi.yaml -o dist/openapi.yaml
spectral lint dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

This approach keeps source diffs smaller and merge conflicts easier to manage, which is useful in a Git-native API design workflow.

Best for: multi-file OpenAPI projects that need a single bundled artifact for CI, docs, mocks, or code generation.

Limit: Its default linting is lighter than a fully customized Spectral ruleset. Many teams use Redocly for bundling and Spectral or vacuum for deeper style enforcement.

openapi-generator: generate SDKs, stubs, and documentation

openapi-generator is Apache-2.0 and generates client SDKs, server stubs, and documentation from OpenAPI definitions.

Install the CLI:

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Generate a TypeScript Axios client:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Swap the generator target for the language you need:

openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

A practical CI pattern is:

redocly bundle openapi.yaml -o dist/openapi.yaml
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./generated/client
Enter fullscreen mode Exit fullscreen mode

Treat the API definition as the source of truth, then regenerate clients and docs when the contract changes. This is a core schema-first practice covered in API design principles.

Best for: keeping generated clients, server stubs, and documentation aligned with the API contract.

Limit: It requires JDK 11+, generated code often needs customization, and output quality differs by language target. Review generated code before shipping it.

oasdiff: block breaking API changes in pull requests

A linter can tell you whether a spec is valid. It cannot tell you whether changing a response field broke existing clients.

oasdiff is an Apache-2.0 Go tool that compares two OpenAPI specs and reports compatibility changes.

Install it:

go install github.com/oasdiff/oasdiff@latest
Enter fullscreen mode Exit fullscreen mode

Check for breaking changes:

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Use the other commands depending on the output you need:

# Only breaking changes
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Human-readable summary of all changes
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Full machine-readable diff
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

In CI, compare the pull-request version with the base branch version:

oasdiff breaking \
  main/openapi.yaml \
  dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

If the command exits with an error for a breaking change, the pull request fails before the incompatible contract is released.

Best for: enforcing backward compatibility in pull-request checks.

Limit: It only compares specs. If the spec is outdated relative to the deployed API, its results will be incomplete. Pair it with linting and keep the contract current.

Optic: lint and diff in one CLI, with a maintenance caveat

Optic is MIT-licensed and combines OpenAPI linting with spec diffing. It can compare two versions and flag breaking changes, and it could also generate a spec from observed test traffic.

Install and run a compatibility check:

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

However, maintenance status matters: Optic’s public repository was archived in early 2026 and is no longer actively maintained. The MIT-licensed source remains available and can still run in an existing pipeline, but it will not receive new rules or security patches.

Best for: teams that already use Optic and need to maintain an existing pipeline.

Limit: Treat it as legacy tooling. For a maintained breaking-change workflow, prefer oasdiff and plan a migration path.

Where Apidog fits—and where it does not

Apidog is not open source, and it does not lint OpenAPI definitions or enforce your style guide. For linting, use Spectral, vacuum, or Redocly.

Apidog provides a different workflow: its free tier and apidog-cli offer an integrated way to design endpoints and schemas, then export OpenAPI for the open-source checks above.

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

You can then run the exported contract through the rest of the pipeline:

apidog export --format openapi -o openapi.yaml
spectral lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

The CLI includes command groups for endpoint, schema, mock, and import/export. See the complete Apidog CLI guide for the full command set.

The important distinction: Apidog is a commercial integrated design-and-export tool that can feed an open-source OpenAPI pipeline. It is not an open-source project and not a replacement for linting.

How to choose a toolchain

Most teams should use multiple tools rather than look for one CLI that does everything.

Tool Best for Install Open source? Notes
Spectral Style-guide linting npm i -g @stoplight/spectral-cli Yes (Apache-2.0) Reference linter; supports custom rules
vacuum Fast linting at scale brew install --cask daveshanley/vacuum/vacuum Yes (MIT) Runs Spectral rulesets
Redocly CLI Bundling and validation npm i -g @redocly/cli Yes (MIT) Useful for multi-file $ref specs
openapi-generator SDK, stub, and doc generation npm i -g @openapitools/openapi-generator-cli Yes (Apache-2.0) Requires JDK 11+
oasdiff Breaking-change detection go install github.com/oasdiff/oasdiff@latest Yes (Apache-2.0) Use in pull-request checks
Optic Lint and diff in one CLI npm i -g @useoptic/optic Yes (MIT) Archived early 2026; legacy
Apidog CLI Integrated design and export npm i -g apidog-cli No (free tier) Not a linter; exports OpenAPI

A practical baseline pipeline looks like this:

# 1. Enforce API style
spectral lint openapi.yaml --ruleset .spectral.yaml

# 2. Produce one distributable OpenAPI artifact
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. Prevent incompatible changes
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 4. Generate an SDK from the validated contract
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Use vacuum instead of Spectral when fast execution on large specs is your priority. Use Redocly when your source spec is split across multiple files. Add openapi-generator only when generated SDKs, server stubs, or docs are part of your delivery workflow.

For more tooling options, see Swagger alternatives for API design and testing and how to design REST APIs.

Wrapping up

The open-source CLI toolchain for API design is mature:

  • Spectral and vacuum enforce style rules.
  • Redocly CLI bundles and validates multi-file definitions.
  • openapi-generator creates clients, stubs, and documentation.
  • oasdiff blocks breaking changes.
  • Optic is a legacy option to recognize in existing pipelines.

Wire these tools into CI and every push validates the API contract without per-seat costs or vendor lock-in.

If you prefer to design endpoints and schemas in one integrated tool, then export OpenAPI into the same pipeline, Download Apidog and try apidog-cli. It complements the open-source stack rather than replacing your linter.

Top comments (0)