How to Use the Apidog CLI in Cursor

Cursor’s Agent can edit files, run terminal commands, read output, and fix regressions. To make API tests part of that loop, let Cursor run your real Apidog scenarios, inspect the exit code, and iterate. The missing piece is a CLI command Cursor can execute.

Try Apidog today

That CLI is apidog-cli, an npm package that runs test scenarios you built visually in Apidog from your terminal. This guide shows how to wire it into Cursor with a project rule, how to prompt the Agent to run tests, how to use the exit code in the edit-test-fix loop, and how to optionally connect the Apidog MCP server so Cursor can read your API spec while coding.

If the CLI is not installed yet, start with how to install the Apidog CLI with an AI coding agent. Come back once this prints a version number:

apidog --version

You also need an Apidog account with at least one saved test scenario.

What “use the CLI in Cursor” means

There is no Apidog plugin for Cursor, and you do not need one. Cursor’s Agent can already run shell commands in your project terminal.

Using Apidog CLI in Cursor means:

1. Teach Cursor the workflow once with a project rule.
2. Have the Agent run apidog run as part of its normal test loop.
3. Optionally connect the Apidog MCP server so Cursor can read your API spec while writing implementation code.

The project rule is what turns this from “type a command in a terminal” into a repeatable Cursor workflow.

Step 1: Add a Cursor project rule

Cursor reads project rules from:

.cursor/rules

Each rule is an .mdc file that can be committed with your repo, so everyone on the team gets the same Agent behavior.

Create the rule in either of these ways:

• Type /create-rule in Cursor chat and describe the rule.
• Open Cursor Settings > Rules, Commands, then click + Add Rule.

Save this file as:

.cursor/rules/apidog-cli.mdc

---
description: "How to run Apidog API tests from the terminal"
alwaysApply: false
---

# Running Apidog API tests

This project has API test scenarios in Apidog. Run them with the
apidog-cli, which is installed globally and already authenticated.

- The command is `apidog run`. The binary is `apidog`.
- Run a single scenario by ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
  - `-t` is the test scenario ID, `-e` is the environment ID.
  - `-n 1` runs it once. `-r cli` prints a readable report to the terminal.
- Do not pass `--access-token`. Auth is handled by a prior `apidog login`.
- The exit code is the source of truth: `0` means every assertion passed,
  non-zero means a failure. Report the exit code, not just a summary.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
  Never guess at flag names.
- After changing code that touches an endpoint, run the relevant scenario
  and read the result before claiming the change works.

Key details:

• description plus alwaysApply: false makes Cursor apply the rule when the chat is relevant.
• Use alwaysApply: true if you want the rule always loaded.
• The rule tells Cursor that the exit code is authoritative.
• The rule prevents the Agent from guessing CLI flags or ignoring failed runs.

Step 2: Get a known-good command from Apidog

Before asking Cursor to run tests, get the real scenario and environment IDs from Apidog.

In Apidog:

1. Open your test scenario.
2. Go to the CI/CD tab.
3. Choose the command-line option.
4. Copy the generated apidog run command.

Example:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

In this example:

• 605067 is the test scenario ID.
• 1629989 is the environment ID.

If your CLI is already authenticated with apidog login, remove the token flag before giving the command to Cursor:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Step 3: Ask Cursor Agent to run the scenario

Open Cursor’s Agent chat mode. Use Agent mode, not inline edit mode, because the Agent can run terminal commands.

Prompt it with:

Run my Apidog test scenario and show me the full output and the exit code.

Cursor should propose a command like:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Approve the terminal command when Cursor asks.

After the run finishes, check the exit code:

• 0 means all assertions passed.
• Non-zero means at least one assertion failed.

Do not rely only on the Agent’s summary. If Cursor says the test passed but the exit code is non-zero, the test failed.

For other report formats or flags, ask Cursor to inspect the installed CLI version:

apidog run --help

The complete Apidog CLI guide covers available flags, including html, json, and junit reporters and data-driven iteration.

Step 4: Use the CLI report in Cursor’s fix loop

The -r cli reporter prints results directly to the terminal, which Cursor can read.

The report includes:

• The scenario that ran
• Each request
• Assertion results
• Failure details
• Final pass/fail count

When a scenario fails, continue in the same Agent chat:

The scenario failed. Read the failing assertion in the report, find the handler that produces that field, and propose a fix. Then run the scenario again and show me the new exit code.

Now the workflow becomes:

1. Cursor reads the failed assertion.
2. Cursor finds the relevant implementation.
3. Cursor edits the code.
4. Cursor reruns apidog run.
5. Cursor checks the new exit code.
6. You approve or continue iterating.

This puts API scenario tests into the same edit-test-fix loop Cursor already uses for unit tests, except these checks run against real endpoints.

For the broader testing pattern, see how to use AI agents for API testing.

Optional: Connect the Apidog MCP server

The CLI lets Cursor run your tests. The Apidog MCP server lets Cursor read your API spec while writing code.

Used together:

• MCP gives Cursor access to your API contract.
• The CLI verifies the implementation against real Apidog scenarios.

Cursor supports MCP servers through JSON config.

For project-scoped config, create:

.cursor/mcp.json

For global config, use:

~/.cursor/mcp.json

Example:

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

A few implementation notes:

• Some Cursor installs require MCP to be enabled in settings.
• Open Cursor Settings and confirm the Apidog MCP server is enabled.
• Do not commit hardcoded tokens.
• If you commit .cursor/mcp.json, reference an environment variable instead.

For the full setup, including project ID and token details, see the Apidog MCP server guide.

For a packaged workflow instead of manual wiring, see the Apidog CLI with Claude Skills guide.

Move the same command into CI

Once Cursor can run the scenario locally, you have already validated the command your CI pipeline can use.

The CI version is the same command:

apidog run -t 605067 -e 1629989 -n 1 -r cli

The main difference is authentication:

• Locally, you can use apidog login.
• In CI, pass the token as a masked secret.

You can also ask Cursor to generate the CI step because the command is already captured in the project rule.

For GitHub Actions setup details, including secrets, reporters, and exit-code gating, see Apidog CLI in GitHub Actions.

Common snags

The rule does not apply

With description and alwaysApply: false, Cursor only loads the rule when it thinks the chat is relevant.

Fixes:

• Mention the rule with @apidog-cli in chat.
• Change the rule to alwaysApply: true.

The Agent cannot run the command

If Cursor only suggests commands instead of running them:

• Confirm you are in Agent mode.
• Check for a terminal approval prompt.
• Approve the command execution.

If the terminal says apidog: command not found, it is likely a PATH issue. The install guide covers that setup.

apidog whoami says you are not authenticated

Authentication is stored on your machine, not inside Cursor.

Run this yourself:

apidog login --with-token

Then ask Cursor to verify:

apidog whoami

Do not paste access tokens into Cursor chat.

Cursor invents a flag

If a run fails with an unknown option error, make Cursor inspect the installed CLI help:

apidog run --help

Then use the exact flag names from the output.

Wrapping up

The Cursor setup is one rule file and one habit:

• Add .cursor/rules/apidog-cli.mdc.
• Tell Cursor how to run apidog run.
• Make the exit code the source of truth.
• Let the Agent rerun scenarios after implementation changes.

You still author scenarios visually in Apidog. Cursor just runs them as part of the development loop.

From here, move the same command into your pipeline with Apidog CLI in GitHub Actions, or review the full flag reference in the complete Apidog CLI guide.