How to migrate from Swagger CLI to Apidog CLI

If you still run swagger-cli validate and swagger-cli bundle in CI, you’re depending on a deprecated tool. The swagger-cli GitHub repo now states that the package is no longer maintained and points users to alternatives.

Try Apidog today

This migration guide shows how to replace Swagger CLI with Apidog CLI without breaking your pipeline. If you only want to keep using the old tool, the Swagger CLI guide covers validate and bundle. Here, the goal is to move the workflow into Apidog CLI.

Download Apidog if you want to follow along. It’s free to start, no credit card required.

Why migrate now

swagger-cli still works, but it no longer receives bug fixes or spec updates. Keeping it in CI means your API contract workflow depends on unmaintained tooling.

If you only need a terminal-native replacement for validation and bundling, Redocly CLI is the closest drop-in option. Its lint command validates OpenAPI structure, and redocly bundle follows $ref pointers similarly to swagger-cli bundle. Redocly also provides its own migration guide.

Use Apidog CLI when you want the spec to become part of a broader API workflow:

• Import and validate OpenAPI definitions
• Resolve multi-file $ref structures
• Export consolidated OpenAPI files
• Generate HTML or Markdown docs
• Run API test scenarios in CI
• Manage mocks, environments, branches, schemas, and endpoints

Choose based on workflow:

• Use Redocly if you want a lightweight linter and bundler.
• Use Apidog if you want design, mocking, testing, docs, and CI automation around the same API project.

What Swagger CLI did vs what Apidog CLI does

Swagger CLI had two main commands:

swagger-cli validate openapi.yaml
swagger-cli bundle openapi.yaml -o out.json

Those commands did two things:

• Validate a Swagger 2.0 or OpenAPI 3.0 document
• Follow $ref pointers and bundle a multi-file definition into one file

Apidog CLI maps those jobs into an import/export workflow:

• apidog import imports an OpenAPI definition into an Apidog project and validates it during import.
• apidog export exports a consolidated OpenAPI file from the project.
• apidog run executes test scenarios and can output CI-friendly reports such as JUnit.
• Resource commands such as endpoint, schema, mock, environment, and branch let you manage project assets from the terminal.

Important limitation: Apidog validates structure on import, but it is not a configurable style-guide linter. There is no apidog lint command and no custom ruleset system. If you need Spectral-style or Redocly-style lint rules, keep a dedicated linter in CI.

Install and log in

Install Apidog CLI globally:

npm install -g apidog-cli@latest

Authenticate with an access token:

apidog login --with-token <TOKEN>

You can generate the token in Apidog:

1. Open the Apidog app or web app.
2. Click your avatar.
3. Go to Account Settings.
4. Open API Access Token.
5. Generate a token.

The CLI stores credentials in:

~/.apidog/config.toml

Treat the token like any other CI secret. Do not commit it or print it in logs.

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

Command mapping

Swagger CLI command	Apidog CLI equivalent	What changes
swagger-cli validate openapi.yaml	apidog import --project <id> --format openapi --file ./openapi.yaml	Validation happens during import. Invalid specs fail the command.
swagger-cli bundle openapi.yaml -o out.json	apidog import ... then apidog export --project <id> --format openapi --output ./out.json	Bundling becomes export from an Apidog project.
swagger-cli bundle -t yaml	apidog export --project <id> --format openapi --output ./out.yaml	Output format follows the output file.
No equivalent	apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1	Export as OpenAPI 3.1.
No equivalent	apidog export --project <id> --format html --output ./docs.html	Generate standalone HTML docs.
No equivalent	apidog export --project <id> --format markdown --output ./docs.md	Generate Markdown docs.
No equivalent	apidog run --project <id> -t <scenarioId> -e <envId> -r junit	Run API tests in CI.

The key migration pattern is:

# Old
swagger-cli validate openapi.yaml
swagger-cli bundle openapi.yaml -o dist/openapi.json

# New
apidog import --project <id> --format openapi --file ./openapi.yaml
apidog export --project <id> --format openapi --output ./dist/openapi.json

The --oas-version flag is useful when modernizing older contracts. For example, you can export as OpenAPI 3.1:

apidog export \
  --project <id> \
  --format openapi \
  --output ./dist/openapi.json \
  --oas-version 3.1

If your main goal is documentation output, see the guide on exporting OpenAPI to Markdown.

Step-by-step migration

1. Get your Apidog project ID

Create or open a project in Apidog.

You can find the project ID in the project settings or in the project URL. You’ll pass it to CLI commands with --project.

Example:

export APIDOG_PROJECT_ID=123456

2. Import the root OpenAPI file

Point Apidog CLI at your root spec file:

apidog import \
  --project "$APIDOG_PROJECT_ID" \
  --format openapi \
  --file ./openapi.yaml

For multi-file specs, import the root file. Apidog resolves referenced files during import.

If the OpenAPI document is malformed or a $ref cannot be resolved, the command fails. This replaces your old validation gate:

swagger-cli validate openapi.yaml

3. Verify the imported project once

Open the project in Apidog and confirm that endpoints, schemas, parameters, and request/response definitions imported correctly.

This is worth doing during migration because Apidog is not just processing a loose file. It is moving the definition into a project workspace.

4. Export the consolidated spec

When you need a single output file for client generation, downstream tooling, or CI artifacts, export it:

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format openapi \
  --output ./dist/openapi.json \
  --oas-version 3.1

This replaces:

swagger-cli bundle openapi.yaml -o dist/openapi.json

5. Add test execution if you use Apidog scenarios

If you have test scenarios in Apidog, run them headlessly:

apidog run \
  --project "$APIDOG_PROJECT_ID" \
  -t <scenarioId> \
  -e <envId> \
  -r "cli,junit" \
  --out-dir ./reports

A failed scenario returns a non-zero exit code, so CI can block the merge.

GitHub Actions example

This workflow:

1. Checks out the repo
2. Installs Node.js
3. Installs Apidog CLI
4. Logs in with a secret token
5. Imports the spec to validate it
6. Exports a consolidated OpenAPI file
7. Runs Apidog test scenarios

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec
        run: |
          apidog import \
            --project 123456 \
            --format openapi \
            --file ./openapi.yaml

      - name: Export consolidated spec
        run: |
          mkdir -p ./dist

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

      - name: Run test scenarios
        run: |
          apidog run \
            --project 123456 \
            -t 7890 \
            -e 4567 \
            -r "cli,junit" \
            --out-dir ./reports

Store the token as APIDOG_ACCESS_TOKEN in your repository secrets.

The reporter option:

-r "cli,junit"

prints CLI output and writes JUnit XML reports. Your CI system can then display API test results alongside other test reports.

For more CI patterns, see the Apidog CLI CI/CD guide and the Apidog CLI with GitHub Actions walkthrough.

What you gain beyond validate and bundle

Mock servers

After the spec is imported into an Apidog project, you can use it to serve mock responses.

That lets frontend or integration teams build against the contract before the backend is complete. Swagger CLI did not provide runtime behavior or mocking.

Automated API test scenarios

apidog run executes API test scenarios against a running API.

The practical CI flow is:

1. Design or import the API contract.
2. Build test scenarios in Apidog.
3. Run them in CI with apidog run.
4. Fail the build if the implementation no longer matches the expected behavior.

A valid OpenAPI file only proves that the contract is structurally valid. Test scenarios check whether the implementation behaves as expected.

HTML and Markdown docs

You can export docs from the same project:

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format html \
  --output ./docs.html

Or:

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format markdown \
  --output ./docs.md

This removes the need to maintain a separate documentation generation step if Apidog’s export formats fit your workflow.

Keep a linter if you need style rules

Apidog CLI validates OpenAPI structure during import, but it does not replace a configurable API style-guide linter.

If your current pipeline enforces rules such as:

• Operation IDs must follow a naming convention
• Every endpoint must have a description
• Every response must include examples
• Error schemas must follow a standard shape

keep a dedicated linter in CI.

For example, you can run Spectral before importing into Apidog:

- name: Install Spectral
  run: npm install -g @stoplight/spectral-cli

- name: Lint OpenAPI style rules
  run: spectral lint ./openapi.yaml

- name: Import spec into Apidog
  run: |
    apidog import \
      --project 123456 \
      --format openapi \
      --file ./openapi.yaml

Use the tools together:

• Spectral or Redocly for custom lint rules
• Apidog for import validation, project workflow, mock servers, docs, and API test execution

The OpenAPI linter setup guide covers how to wire a linter into the workflow.