Apidog CLI: The API Client That Lives in Your Terminal

Your API workspace lives in a GUI, but your workday often lives in a terminal. Each context switch costs time and focus—and in CI pipelines or AI-agent sessions, a GUI may not be available at all.

Try Apidog today

The Apidog CLI brings your API workspace to the shell: tests, endpoints, schemas, environments, mock expectations, and docs.

One important distinction: the Apidog CLI is not another curl. Use curl or HTTPie for one-off requests and quickly inspecting JSON. See this roundup of terminal and TUI REST clients for interactive tools.

Use the Apidog CLI when you need to work with an API workspace: run saved test scenarios, read or update API contracts, and import or export specifications from scripts, CI jobs, or AI agents.

What “lives in your terminal” means

Terminal HTTP tools typically handle one request at a time. The Apidog CLI works at the project level.

Job	Commands
Run tests	run, test-scenario, test-suite, test-case, test-data, test-report
Manage the contract	endpoint, schema, folder, common-parameter, response-component, security-scheme
Ship docs and mocks	doc, docs-site, shared-doc, mock
Configure and connect	environment, variables, vault, database-connection, websocket, socketio
Operate as a team	branch, merge-request, runner, scheduled-task, audit-log, import, export

Start with command-level help:

apidog --help
apidog endpoint --help
apidog run --help

Commands return structured JSON. Most responses also include agentHints.nextSteps, which can help scripts and agents determine what command to run next.

Install and authenticate

The CLI is available as the apidog-cli npm package. It runs on macOS, Linux, and Windows and requires Node.js 16 or later.

npm install -g apidog-cli
apidog --version

Create an API access token in Apidog:

1. Open the Apidog app.
2. Click your avatar.
3. Open Account Settings.
4. Copy the value under API Access Token.

Then log in:

apidog login --with-token <YOUR_TOKEN>

The CLI stores the token in ~/.apidog/config.toml. Keep that file, tokens, and CI logs out of version control.

For CI, pass the token from your secret manager instead of relying on local login state:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenario_id> \
  -e <environment_id> \
  -r cli

Useful global flags:

• --project: select a project
• --branch: select a branch
• --access-token: override the saved token
• --api-base-url: connect to a self-hosted Apidog deployment

For CI token setup, see the Apidog CLI authentication guide.

Run visual test scenarios from CI

The primary workflow is straightforward:

1. Build a test scenario in Apidog’s visual editor.
2. Chain requests and extract variables from responses.
3. Add status, header, or body assertions.
4. Run the same scenario from any shell.

Copy the scenario command and IDs from its CI/CD tab:

apidog run -t <scenario_id> -e <env_id> -r cli

The process exits with:

• 0 when every assertion passes
• A non-zero status when an assertion or request fails

That makes it suitable for CI gates without additional glue:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$APIDOG_SCENARIO_ID" \
  -e "$APIDOG_ENV_ID" \
  -r cli,junit

Switch -e to run the same scenario against development, staging, or production environments.

Run data-driven tests

Pass a CSV or JSON data file to iterate a scenario over multiple rows instead of duplicating test steps. See the data-driven testing guide for the workflow.

If you are starting from scratch, follow the step-by-step REST API CLI walkthrough.

Publish test reports

The CLI supports four report formats:

• cli: step-by-step terminal output
• html: browser-readable report
• json: machine-readable output
• junit: CI-friendly test results

Generated files are written to apidog-reports/.

apidog run -t <scenario_id> -e <env_id> -r cli,junit

Use junit for CI test-result publishing and html or json for stored artifacts. See the test reports guide for format examples.

For executions that should not depend on a developer laptop, use runner and scheduled-task to manage self-hosted runners and scheduled runs. This is the same mechanism used for scheduled API tests in Apidog.

Manage the API contract from the terminal

The CLI can also query and modify project resources, not only run tests.

apidog endpoint list --project <project_id>
apidog schema get <schema_id>
apidog environment list
apidog mock list

You can work with:

• Endpoints and folders
• Data schemas
• Environments and variables
• Security schemes and reusable components
• Mock expectations
• Published documentation
• WebSocket and Socket.IO endpoints
• Database connections used by test scenarios

The mock command manages fixed request/response expectations for mock servers. The doc and docs-site commands manage published documentation.

Import and export API specifications

The CLI supports OpenAPI 3.x, Swagger 2.0, and Postman collections. Use it in migration or synchronization scripts to move specifications into or out of a project.

apidog import openapi.json --project <project_id>
apidog export --format openapi

OpenAPI and Swagger support common toolchain integrations; see the Swagger specification for format details.

Use the CLI safely with AI agents

The 2026 CLI releases focus on making API workspaces operable by AI coding agents while keeping changes reviewable.

1. Parse structured command output

Commands return JSON, including agentHints.nextSteps. An agent can use that output to identify valid follow-up commands and error recovery paths.

2. Validate write payloads before applying them

Use cli-schema to inspect and validate the expected JSON for write operations:

apidog cli-schema list
apidog cli-schema get <command_or_resource>
apidog cli-schema validate <payload.json>

Use this write workflow:

1. Get the command schema.
2. Generate the JSON payload.
3. Validate the payload.
4. Run the create or update command.

This prevents malformed payloads from being sent to the project.

3. Load the CLI skill for agent workflows

The skill command packages CLI operating knowledge in a format agents can load directly. Read more about why we built the Apidog CLI skill.

According to Apidog’s measurements, agents using CLI schemas made about 30% fewer tool calls and used 25% fewer tokens than agents guessing payload formats. The methodology is covered in this analysis.

4. Keep AI changes behind permission gates

By default, AI-sourced writes to a branch are blocked until a human enables External AI Edit Permissions.

In Apidog client 2.8.32 or later, configure this under:

Project Settings → Feature Settings → AI Feature Settings

Another option is an AI branch:

1. Create an isolated branch.
2. Let the agent import the resources it needs.
3. Apply and validate edits.
4. Open a merge request for human review.

Untouched AI branches auto-archive after 24 hours, helping experimental branches avoid accumulating.

What the Apidog CLI is not

It is not an interactive request client

There is no command for typing an ad-hoc POST request and pretty-printing the response. Use curl, HTTPie, or TUI clients for that workflow.

It is not open source

The npm package is proprietary, npm is the only installation channel, and commands beyond --help require an Apidog account.

The free tier covers the workflow described here. If an auditable open-source license is required, use an open-source runner instead.

It is not standalone

Scenarios, endpoints, and environments live in an Apidog project rather than local files. In exchange, the platform provides a shared source of truth across API design, testing, mocking, and documentation.

Where it fits in a terminal workflow

The key difference between API test runners is where tests are authored:

Tool	Test authoring model
Newman / Postman CLI	Collections authored in Postman
Hurl / Bruno	Text files
Apidog CLI	Visual scenarios in Apidog, alongside contracts, mocks, and docs

For a deeper comparison, see Apidog CLI vs Newman and this roundup of top terminal-based API testing tools.

A practical setup for most teams:

• Use curl or xh for quick exploratory requests.
• Use apidog run for repeatable suites in CI.
• Use cli-schema validate before agent-driven writes.
• Use branches and merge requests to review contract changes.

To get started with CI, use the copy-paste workflow in the GitHub Actions walkthrough.

FAQ

Is the Apidog CLI free to use?

Yes. The package installs free from npm, and Apidog’s free tier covers building scenarios and running them through the CLI. Paid plans add team-scale features rather than basic CLI access.

Does it replace curl or HTTPie?

No. curl and HTTPie are designed for ad-hoc requests. The Apidog CLI runs saved scenarios and manages project resources. Most developers will use both.

Can it run fully headless in CI?

Yes. Pass --access-token from a CI secret, run apidog run with a scenario ID, and fail the build when the command exits non-zero. The runner does not need the desktop app.

What formats can it import and export?

OpenAPI 3.x, Swagger 2.0, and Postman collections.

How can AI agents use it safely?

Use the schema-validate-write workflow and permission gates. cli-schema validate catches malformed payloads before they are applied, while AI branches isolate agent changes until a human reviews and merges them. See how to use the Apidog CLI in Claude Code.

The terminal is where tests run and where agents work. Installing the API workspace client there removes a context switch from both workflows.

Download Apidog, install the CLI from npm, and run one scenario end to end. The Apidog CLI page includes the full command reference when you are ready to go beyond run.