DEV Community

Cover image for The best Swagger CLI alternative in 2026
Hassann
Hassann

Posted on • Originally published at apidog.com

The best Swagger CLI alternative in 2026

If you installed @apidevtools/swagger-cli and saw deprecation warnings, here’s the practical takeaway: swagger-cli is no longer maintained. The swagger-cli repository on GitHub is marked deprecated, and its README points users to Redocly CLI as the successor.

Try Apidog today

This guide focuses specifically on the swagger-cli terminal tool: the one that runs validate and bundle. If you’re looking for alternatives to Swagger Editor, SwaggerHub, or a broader API design platform, see 7 Swagger alternatives that also test your API.

Let’s map what swagger-cli actually did, then walk through the tools you can use instead.

What swagger-cli actually did

swagger-cli had a narrow scope. It exposed two commands:

# Validate a Swagger 2.0 / OpenAPI 3.0 definition against the schema and check $refs
swagger-cli validate openapi.yaml

# Follow $ref pointers and combine a multi-file definition into one file
swagger-cli bundle openapi.yaml -o bundled.json
Enter fullscreen mode Exit fullscreen mode

The bundle command supported a small set of options:

# Write output to a file
swagger-cli bundle openapi.yaml -o bundled.json

# Choose output type
swagger-cli bundle openapi.yaml --type yaml

# Dereference all $refs
swagger-cli bundle openapi.yaml --dereference

# Format output indentation
swagger-cli bundle openapi.yaml --format 2
Enter fullscreen mode Exit fullscreen mode

That was the entire tool.

It did not:

  • enforce style rules
  • generate documentation
  • run API tests
  • start mock servers
  • manage API projects

So when replacing swagger-cli, first decide which job you need:

  • schema validation
  • bundling
  • linting and governance
  • docs generation
  • mocking
  • testing
  • a full API lifecycle workflow

The shortlist

Most swagger-cli migrations fall into one of these options:

  1. Redocly CLI — closest replacement for validate and bundle
  2. Apidog — better if validate/bundle are part of a larger API workflow
  3. Spectral — dedicated OpenAPI linting in CI
  4. openapi-generator / vacuum — useful for specific cases

Redocly CLI: the official successor and closest 1:1 swap

Redocly CLI is the replacement recommended by swagger-cli’s own README. The package is @redocly/cli, and the binary is redocly.

Redocly also provides a migration guide from swagger-cli.

Redocly CLI

Install it globally:

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

Or run it with npx:

npx @redocly/cli@latest lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

The command mapping is straightforward:

# swagger-cli validate openapi.yaml
redocly lint openapi.yaml

# swagger-cli bundle openapi.yaml -o output.json
redocly bundle openapi.yaml --output output.json
Enter fullscreen mode Exit fullscreen mode

Bundle flag mapping

swagger-cli Redocly CLI Purpose
-o, --outfile --output or -o Write to a file
-t, --type --ext (json, yaml, yml) Output format
-r, --dereference -d, --dereferenced Fully inline all $refs

Example migration:

# Before
swagger-cli bundle openapi.yaml -o bundled.json -t json

# After
redocly bundle openapi.yaml --output bundled.json --ext json
Enter fullscreen mode Exit fullscreen mode

Dereference all references:

redocly bundle openapi.yaml --dereferenced --output dereferenced.yaml
Enter fullscreen mode Exit fullscreen mode

Important difference: lint does more than validate

swagger-cli validate only checked structural validity and references.

redocly lint can also apply style-guide rules. That is useful for API governance, but it may produce warnings or errors that swagger-cli never reported.

If you want behavior closer to plain swagger-cli validation, configure Redocly with the spec ruleset.

Example redocly.yaml:

apis:
  main:
    root: openapi.yaml

extends:
  - spec
Enter fullscreen mode Exit fullscreen mode

Then run:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Redocly also supports other rulesets such as minimal, recommended, and recommended-strict, plus custom rules.

For a deeper linter setup, see the best OpenAPI linter setup.

Redocly CLI can also build docs

swagger-cli did not generate documentation. Redocly CLI can:

redocly build-docs openapi.yaml -o docs.html
Enter fullscreen mode Exit fullscreen mode

It can also split a single OpenAPI file into multiple files:

redocly split openapi.yaml --outDir ./openapi
Enter fullscreen mode Exit fullscreen mode

Use Redocly CLI if your workflow should remain code-first, terminal-native, and focused on linting, bundling, and docs generation.

What it does not do:

  • run API tests
  • host mock servers
  • manage a full API lifecycle workspace

Apidog: when validate and bundle are only part of the workflow

swagger-cli was a static utility. It validated a file and bundled a file.

For many teams, that is only the first step. After the OpenAPI file is valid, developers often need to:

  • import it into a workspace
  • generate mocks
  • publish docs
  • run API tests
  • export a bundled spec for CI or downstream tools

Apidog

Apidog is an all-in-one API platform for design, mocking, testing, and documentation. It also provides a CLI for import, export, CI test runs, and project resource management.

Instead of only producing a bundled file, Apidog lets you turn the spec into a project workspace.

Install and authenticate the Apidog CLI 

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

You can get the token from the Apidog app or web interface:

  1. Open your avatar menu.
  2. Go to Account Settings.
  3. Open API Access Token.
  4. Generate or copy your token.

The CLI stores the token in:

~/.apidog/config.toml
Enter fullscreen mode Exit fullscreen mode

Do not print it in CI logs or commit it to your repository.

Use import as the validate step

apidog import ingests an API definition into a project. It resolves multi-file $refs into project resources and surfaces malformed input during import.

apidog import --project 123456 --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Apidog supports multiple import formats, including:

  • OpenAPI
  • Postman
  • HAR
  • Insomnia
  • WSDL
  • JSON Schema

That is useful when your API sources come from different tools.

Use export as the bundle step

apidog export emits a consolidated output file from your project.

You can also choose the OpenAPI version during export:

# Bundle and export as OpenAPI 3.1
apidog export \
  --project 123456 \
  --format openapi \
  --output ./openapi.json \
  --oas-version 3.1
Enter fullscreen mode Exit fullscreen mode

Export standalone HTML documentation:

apidog export \
  --project 123456 \
  --format html \
  --output ./docs.html
Enter fullscreen mode Exit fullscreen mode

So the swagger-cli-style mapping looks like this:

# swagger-cli validate
apidog import --project 123456 --format openapi --file ./openapi.json

# swagger-cli bundle
apidog export --project 123456 --format openapi --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Run API tests in CI

swagger-cli did not run tests. Apidog CLI can.

Run a test scenario:

apidog run \
  --project 123456 \
  -t <testScenarioId> \
  -e <environmentId> \
  -r "cli,html,json,junit"
Enter fullscreen mode Exit fullscreen mode

Run fully offline from an exported collection file:

apidog run ./collection.apidog-cli.json
Enter fullscreen mode Exit fullscreen mode

This is useful when your CI pipeline needs test reports in multiple formats, including JUnit.

Manage project resources from the CLI

The Apidog CLI can also work with resources such as:

  • endpoint
  • schema
  • mock
  • environment
  • branch
  • test-suite
  • test-report

For full CLI setup and flags, see the Apidog CLI complete guide and the official Apidog CLI docs.

Where Apidog is not a swagger-cli clone

Apidog is not a code-first OpenAPI linter like Redocly CLI or Spectral.

Its limits:

  • no apidog lint command
  • no configurable Spectral-style custom rulesets through the CLI
  • no split command
  • no join command
  • not open source
  • GUI-first for design, mocking, visual test building, and docs

Use Apidog when you want a workspace around the API lifecycle, not just a terminal-only bundler.

Spectral: pure, customizable linting in CI

If your real need is OpenAPI governance in pull requests, use Spectral.

Spectral is open source and focused on linting JSON/YAML documents, including OpenAPI.

Spectral

Install it:

npm install -g @stoplight/spectral-cli
Enter fullscreen mode Exit fullscreen mode

Run it:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Add a ruleset file:

# .spectral.yaml
extends:
  - spectral:oas

rules:
  operation-operationId: error
  operation-description: warn
Enter fullscreen mode Exit fullscreen mode

Run again:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral is best when you want to enforce API standards as code.

It does not:

  • bundle OpenAPI files
  • generate docs
  • run tests
  • mock APIs

A common setup is:

spectral lint openapi.yaml
redocly bundle openapi.yaml --output bundled.yaml
Enter fullscreen mode Exit fullscreen mode

That gives you strict linting plus bundling.

For more detail, see Spectral OpenAPI linting and validating OpenAPI in CI.

Briefly: openapi-generator and vacuum

Two other tools often come up in swagger-cli replacement discussions.

openapi-generator

openapi-generator is mainly for generating clients, servers, and SDKs from OpenAPI specs.

If you only bundled specs so you could feed them into a generator, check whether your generator can consume your original spec directly. You may not need a separate bundle step.

vacuum

vacuum is a fast OpenAPI linter written in Go. It is Spectral-compatible and useful when linting speed matters, especially in large repositories.

It is not a full validate-plus-bundle replacement by itself.

Comparison table

Tool Validate Bundle Lint rules Docs Mock Test Open source Best for
swagger-cli Yes Yes No No No No Yes, deprecated Nothing new; it is unmaintained
Redocly CLI Yes, via lint Yes Yes, configurable Yes, Redoc HTML No No Yes Drop-in terminal validate/bundle replacement with governance
Apidog Yes, on import Yes, on export with OAS upgrade Structural only, no custom CLI rulesets Yes Yes Yes, via CLI run No, freemium Full API lifecycle workflow
Spectral Yes, lint-based No Yes, custom rulesets No No No Yes Strict OpenAPI linting in CI
vacuum Yes, lint-based No Yes, Spectral-compatible No No No Yes Fast linting on large specs

Recommendation

Use this decision tree:

Do you only need validate + bundle from the terminal?
└─ Yes → Use Redocly CLI

Do you need custom API style rules in CI?
└─ Yes → Use Spectral, optionally with Redocly CLI for bundling

Do you need mocks, tests, docs, import/export, and CI runs?
└─ Yes → Use Apidog

Do you only need generated clients/servers?
└─ Yes → Check openapi-generator first
Enter fullscreen mode Exit fullscreen mode

Pick Redocly CLI if you want the closest swagger-cli replacement

Redocly CLI is the cleanest migration path.

Use it when your workflow is:

lint spec
bundle spec
publish or commit output
Enter fullscreen mode Exit fullscreen mode

Migration is almost mechanical:

# Before
swagger-cli validate openapi.yaml
swagger-cli bundle openapi.yaml -o bundled.yaml

# After
redocly lint openapi.yaml
redocly bundle openapi.yaml --output bundled.yaml
Enter fullscreen mode Exit fullscreen mode

It is also the best choice if you want to stay open source, code-first, and terminal-native.

Pick Apidog if validate and bundle are only the start

Use Apidog if your actual workflow is closer to:

import spec
validate structure
create mocks
write tests
publish docs
export bundled OpenAPI
run tests in CI
Enter fullscreen mode Exit fullscreen mode

In that case, swagger-cli was only solving one small part of the API lifecycle.

Apidog’s CLI gives you the automation layer:

apidog import --project 123456 --format openapi --file ./openapi.json

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
Enter fullscreen mode Exit fullscreen mode

Redocly CLI and Apidog are not identical tools.

  • Redocly CLI is a lightweight terminal specialist.
  • Apidog is an API lifecycle platform with CLI support.

Choose based on how much workflow you want the tool to own.

If you only want lint and bundle, Redocly CLI is leaner. If you want the spec to become mocks, tests, docs, and CI runs, Apidog is the broader fit.

FAQ

Is swagger-cli still maintained?

No. The swagger-cli GitHub repository is marked deprecated and no longer maintained. It may still install and run, but it will not receive fixes or updates.

Plan a migration.

What replaced swagger-cli?

The swagger-cli README points to Redocly CLI as the successor.

Use this mapping:

# swagger-cli validate
redocly lint openapi.yaml

# swagger-cli bundle
redocly bundle openapi.yaml --output bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Redocly also provides a dedicated migration guide.

If you need more than validation and bundling, Apidog covers import, export, mocks, tests, and docs in one workspace.

Is Apidog free?

Apidog is freemium. You can start on a free tier without a credit card, with paid plans available for larger teams and advanced needs.

It is not open source, which is an important difference from Redocly CLI and Spectral.

Can I keep my swagger-cli workflow exactly as-is?

The closest replacement is Redocly CLI.

To mimic swagger-cli’s structural validation, configure Redocly with the spec ruleset and run:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

For bundling, the commands and flags are almost one-to-one:

redocly bundle openapi.yaml --output bundled.yaml
Enter fullscreen mode Exit fullscreen mode

For more context on the original tool, see how to use swagger-cli from the terminal.

Top comments (0)