If you came here after running npm install -g @apidevtools/swagger-cli and noticing the warnings, here’s the short version: the tool is no longer maintained. The swagger-cli repository on GitHub states plainly that it’s deprecated, citing “the maintenance burden of trying to keep up with the expectations of a huge userbase with little to no contributions.” The README itself points you toward Redocly CLI as the successor.
So you need a replacement. This is specifically about the swagger-cli terminal tool, the one that does validate and bundle. If you actually mean the Swagger Editor, SwaggerHub, or the broader design suite, read 7 Swagger alternatives that also test your API instead.
Let’s look at what swagger-cli did, then walk through the honest shortlist of what to use now.
What swagger-cli actually did
It’s worth being precise, because the right replacement depends on what you were using.
swagger-cli had exactly 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
The bundle command had a small set of options: -o/--outfile to write to a file, -t/--type to pick JSON or YAML, -r/--dereference to fully inline every $ref, and -f/--format for indentation.
That’s the whole tool. It validated structure and it bundled multi-file specs. It did not lint with style rules, generate docs, run tests, or mock anything. If you read claims that swagger-cli “linted” your spec, they’re wrong; it only checked your definition against the OpenAPI schema and resolved references. Keep that scope in mind, because some replacements do far more, and you may or may not want that.
The shortlist
Three tools cover almost every reason you’d reach for swagger-cli, plus a couple of specialists worth a mention. Here’s the honest rundown.
Redocly CLI: the official successor and closest 1:1 swap
Redocly CLI (@redocly/cli, binary redocly) is open source and is the tool swagger-cli’s own README sends you to. Redocly even publishes a migration guide from swagger-cli. If your goal is a drop-in terminal validator and bundler, start here.
Install it the same way you installed swagger-cli:
npm install -g @redocly/cli@latest
# or run without installing
npx @redocly/cli@latest lint openapi.yaml
The mapping is clean. swagger-cli’s validate becomes redocly lint, which checks your spec and applies configurable style rules. swagger-cli’s bundle becomes redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Here’s the bundle flag mapping side by side:
| 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 |
One thing to know: redocly lint does more than swagger-cli’s validate by default. It applies a style-guide ruleset, not just a schema check. If you want the plain structural validation swagger-cli gave you, configure a redocly.yaml with only the spec rule, then run redocly lint openapi.yaml. That ruleset behavior is Redocly’s signature strength rather than a drawback; it’s why teams who want terminal-native governance like it. You can tune rulesets (minimal, recommended, recommended-strict, spec) or write custom rules. See the best OpenAPI linter setup for how that fits alongside other linters.
Redocly CLI also goes beyond swagger-cli’s two commands. It can split a single description into a multi-file structure (the inverse of bundle), join multiple files (experimental), and build standalone Redoc HTML docs:
redocly build-docs openapi.yaml -o docs.html
What it does not do: run API tests or host a mock server. It’s a code-first, terminal-native lint/bundle/docs tool, and an excellent one. If that’s all you need, you can stop reading and migrate today.
Apidog: when you want more than validate plus bundle
Here’s the honest reframe. swagger-cli was a static script you ran to validate and bundle. But for most teams, validating and bundling are means to an end. You validate so the spec is correct, you bundle so it’s portable, and then you mock it, test it, and document it. swagger-cli handed those later steps off to other tools.
Apidog closes that gap. It’s an all-in-one API platform: design, mock, test, and docs in one workspace, with a CLI that handles import, export, and CI test runs. Where swagger-cli gave you a file, Apidog gives you a living workspace built from that file.
The two commands that map most directly to your swagger-cli muscle memory are import and export. Install the CLI and authenticate first:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
You get the token from the Apidog app or web: avatar, then Account Settings, then API Access Token. It’s stored in ~/.apidog/config.toml, so never print it or commit it.
Import is your validate step. It ingests a definition into a project and resolves multi-file $refs into unified resources. If the file is malformed, the import surfaces it:
apidog import --project 123456 --format openapi --file ./openapi.json
Import accepts a long list of formats beyond OpenAPI, including Postman, HAR, Insomnia, WSDL, and JSON Schema, which is handy when your sources are mixed.
Export is your bundle step, with a bonus. It emits a single consolidated file, and you choose the OpenAPI version on the way out. That makes it bundle plus an optional spec upgrade in one command:
# Bundle and upgrade to OpenAPI 3.1 in one shot
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Or emit standalone HTML docs
apidog export --project 123456 --format html --output ./docs.html
For CI, Apidog adds the step swagger-cli never had: running tests.
# Run a test scenario in CI with multiple report formats
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Or run fully offline from an exported collection file
apidog run ./collection.apidog-cli.json
The CLI also manages project resources directly, including endpoint, schema, mock, environment, branch, test-suite, and test-report. For setup details and every flag, see the Apidog CLI complete guide and the official Apidog CLI docs.
Now the honest limits, because fit matters more than hype. Apidog’s CLI validates structure on import, but it does not give you a configurable, code-first style-guide linter with custom rulesets the way Redocly’s lint does. There is no apidog lint command, and you can’t author Spectral-style custom rules through the CLI. There’s also no split or join. Apidog is GUI-first: design, mocking, visual test building, and docs are primarily authored in the desktop or web app, with the CLI handling import, export, CI test runs, and resource management against a project. And Apidog is freemium, not open source, so it’s a different model from Redocly CLI and Spectral.
Spectral: pure, customizable linting in CI
If what you really wanted from swagger-cli was strict, opinionated validation in your pipeline, the dedicated linter is Spectral from Stoplight. It’s open source and built for one job: applying a customizable ruleset to OpenAPI (and other JSON/YAML) documents.
Spectral shines when you want to enforce house style as code, with your own rules, in every pull request. It doesn’t bundle, doesn’t generate docs, and doesn’t test endpoints; it lints. Pair it with a bundler and you’ve rebuilt a focused version of what swagger-cli did, plus real governance. Our guide to Spectral OpenAPI linting walks through writing rulesets, and validating OpenAPI in CI covers wiring it into a pipeline.
Briefly: openapi-generator and vacuum
Two more tools come up, so here’s the accurate, short version. openapi-generator is a code and client generator; if your reason for bundling was feeding a generator, you may not need a separate bundle step at all, since it consumes specs directly. vacuum is a fast, Spectral-compatible OpenAPI linter written in Go, a good pick when lint speed in large monorepos matters. Neither is a general validate-plus-bundle replacement on its own, but both fit specific needs.
Comparison table
Here’s how the options stack up across the capabilities swagger-cli users tend to care about.
| 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’s unmaintained |
| Redocly CLI | Yes (lint) |
Yes | Yes (configurable) | Yes (Redoc HTML) | No | No | Yes | A drop-in terminal validate/bundle swap with governance |
| Apidog | Yes (on import) | Yes (on export, with OAS upgrade) | Structural only, no custom rulesets | Yes (app + export) | Yes | Yes (CLI run) | No (freemium) | One tool for the whole API lifecycle |
| Spectral | Yes (lint-based) | No | Yes (custom rulesets) | No | No | No | Yes | Strict, customizable linting in CI |
| vacuum | Yes (lint-based) | No | Yes (Spectral-compatible) | No | No | No | Yes | Fast linting on large specs |
The recommendation
This isn’t an “everything is great, pick your favorite” situation. Two clear paths cover almost everyone.
Pick Redocly CLI if you want a drop-in swap. It’s the official successor, it’s open source, and the migration is nearly mechanical: validate to lint, bundle to bundle, with the flag mapping above. If your workflow is genuinely just “validate and bundle from the terminal,” and you’d like to add governance rules later without changing tools, Redocly is the obvious choice. It keeps you code-first and terminal-native, which is exactly where swagger-cli lived.
Pick Apidog if validate and bundle were only the beginning. Most teams don’t validate a spec for its own sake. They validate it, then someone needs a mock to build against, someone else writes tests, and somebody owns the docs. swagger-cli stopped at step one and made you assemble the rest from Spectral, a bundler, Postman, and Newman. Apidog brings import (validate), export (bundle plus an OAS version upgrade), mock, test, and docs into one workspace, with a CLI for the parts that belong in CI. You stop babysitting a static, now-unmaintained script and bring the whole spec into a place where it stays useful after it’s bundled.
These are different paradigms, not competing versions of the same thing. Redocly CLI is the lightweight, config-driven specialist you run purely from the terminal. Apidog is the all-in-one platform that happens to have a capable CLI. Choose based on how much of the lifecycle you want in one tool, and be honest about it: if you only ever want to lint and bundle in the terminal, Redocly is leaner and free.
If you want to try the lifecycle approach, download Apidog and import an existing spec; it’s free to start, no credit card required, and you can see your bundled, versioned output in a few minutes.
FAQ
Is swagger-cli still maintained?
No. The swagger-cli GitHub repository is marked deprecated and no longer maintained, citing low contribution against a large userbase. It still installs and runs, but it won’t get fixes or updates, so plan a migration.
What replaced swagger-cli?
The project’s own README points to Redocly CLI as the successor. redocly lint replaces swagger-cli validate and redocly bundle replaces swagger-cli bundle. Redocly even publishes a dedicated migration guide. If you want more than validate and bundle, Apidog covers import, export, mock, test, and docs in one place.
Is Apidog free?
Apidog is freemium. There’s a free tier you can start on without a credit card, with paid plans for larger teams and advanced needs. It’s not open source, which is the main difference from Redocly CLI and Spectral if open licensing is a requirement for you.
Can I keep my swagger-cli workflow exactly as-is?
Closest is Redocly CLI. To mirror swagger-cli’s plain structural validate, set up a redocly.yaml with only the spec rule and run redocly lint. For bundling, the commands and flags map almost one to one. For a deeper look at the original tool’s scope, see how to use swagger-cli from the terminal.
