How to Use the Apidog CLI in Windsurf

Run Apidog API Tests in Windsurf Cascade

Windsurf’s Cascade agent already follows an edit-test-fix loop: it changes files, runs commands, reads output, and decides what to do next. Add your Apidog API test scenario to that loop so Cascade can run it from the terminal, inspect the exit code, and react to failures instead of leaving tests behind a GUI.

Try Apidog today

Install the apidog-cli npm package, authenticate once, and add a project rule that tells Cascade which scenario to run. Cascade can then execute apidog run alongside your existing unit-test commands.

Before continuing, verify that the CLI is installed and authenticated:

apidog --version

If you need setup instructions, see How to install the Apidog CLI with an AI coding agent.

Which Windsurf setup this applies to

This guide is for Codeium’s Windsurf IDE and its built-in Cascade agent. Cascade runs locally, can read your repository, edit files, and execute shell commands in the integrated terminal. Depending on your auto-execution settings, it may ask for command approval.

If Windsurf is not installed yet, start with how to download and install Windsurf.

Step 1: Add an Apidog rule to .windsurf/rules

Cascade loads project rules from Markdown files in .windsurf/rules/ at the repository root. Put one rule per file.

Windsurf also supports the legacy .windsurfrules file at the workspace root and global rules in ~/.codeium/windsurf/memories/global_rules.md. For a repository-specific test command, use .windsurf/rules/.

See the Windsurf rules and memories reference for the current behavior.

Create this file:

.windsurf/rules/apidog.md

Add the following rule:

# Apidog API tests

This project has Apidog test scenarios. Run them with the Apidog CLI:

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

Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
  Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
  access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.

A rule file is more reliable than a chat instruction:

• It persists across Cascade sessions.
• It is shared with teammates through Git.
• Cascade loads it automatically when it starts in the repository.

Step 2: Copy the real command from Apidog

Do not guess the <scenario_id> or <env_id> values.

In Apidog:

1. Open the test scenario.
2. Open the CI/CD tab.
3. Copy the generated apidog run command.
4. Replace the example command in .windsurf/rules/apidog.md.

The generated command includes the correct scenario ID, environment ID, and reporter options for your project.

For available options, see the apidog run command reference.

Step 3: Ask Cascade to run the scenario

Open Cascade in the repository after adding the rule. It should load .windsurf/rules/apidog.md automatically.

You can make an API-related code change, then ask:

Run the Apidog scenario and tell me the exit code.

Cascade should execute the exact apidog run command defined in the rule.

Whether Cascade runs it immediately depends on your auto-execution mode:

• Disabled: every command needs approval.
• Allowlist Only: only allowlisted commands run automatically.
• Auto: execution is based on a premium-model judgment.
• Turbo: commands run automatically unless denylisted.

To allow Apidog commands without enabling broader automatic execution, add apidog to the windsurf.cascadeCommandsAllowList setting.

You can open settings through the Command Palette and configure:

{
  "windsurf.cascadeCommandsAllowList": ["apidog"]
}

The matching denylist setting is windsurf.cascadeCommandsDenyList. If a command matches both lists, the denylist takes precedence.

See Windsurf’s terminal documentation for details.

Step 4: Read failures in Cascade’s terminal

Use the CLI reporter so Cascade can inspect test output directly:

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

The cli reporter prints each request, assertion result, and summary in the terminal. When a test fails, Cascade can use the failed status code, field, expected value, or actual value to identify the next code change.

To also generate a browser-friendly report, add the HTML reporter:

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

The html reporter writes a self-contained report to:

./apidog-reports

Keep cli enabled so Cascade still receives inline output.

For all supported report formats, including JUnit output for CI systems, see:

• The complete Apidog CLI guide
• How to read Apidog CLI test reports

Put API testing inside Cascade’s loop

Once the rule is in place, Cascade can follow the same workflow it uses for unit tests:

1. Edit an API handler or service.
2. Run the Apidog scenario against the configured environment.
3. Read the terminal output and exit code.
4. Fix the reported failure.
5. Run the scenario again.

For example, if Cascade changes a checkout response handler, your scenario can detect a missing field, incorrect value, or wrong HTTP status before the agent considers the task complete.

The CLI provides the verification step. You still author and maintain scenarios visually in Apidog, while Cascade executes those scenarios during implementation.

For the broader agent-testing pattern, see:

• How to use AI agents for API testing
• The Apidog AI test harness

Verify that Cascade actually ran the CLI

Do not rely only on Cascade’s summary. Verify the command and result.

1. Confirm the command was executed

Look for the literal command and its output in Cascade’s terminal:

apidog run ...

If Cascade says tests ran but there is no command output, ask it to rerun the scenario and show the raw terminal result.

2. Confirm the exit code

Ask Cascade directly:

What was the exit code of that apidog run command?

apidog run returns:

• 0 when all assertions pass
• A non-zero exit code when an assertion fails

Treat the exit code as the source of truth. If Cascade says “tests passed” but the command exited with a non-zero status, the test failed.

3. Confirm the scenario and environment IDs

If the CLI reports that a scenario cannot be found, Cascade may be using an incorrect ID.

Compare the -t and -e values in:

• .windsurf/rules/apidog.md
• The command generated in Apidog’s CI/CD tab

Use the generated command as the canonical source.

Optional: Connect the Apidog MCP server

The rule-based CLI workflow is enough to run tests. If you also want Cascade to access API specifications while writing code, connect an MCP server.

Windsurf supports Model Context Protocol servers through:

~/.codeium/windsurf/mcp_config.json

You can edit that file directly or configure servers through Cascade’s MCP panel. See the Windsurf MCP reference and how to set up MCP servers in Windsurf.

The Apidog MCP server exposes API specifications to MCP-compatible agents.

Use the two integrations for different jobs:

• Apidog CLI: run API test scenarios and return pass/fail results.
• Apidog MCP server: provide API schemas and specifications as context while Cascade writes code.

Troubleshooting common setup issues

Cascade ignores the rule

Check that the file:

• Is located at .windsurf/rules/apidog.md
• Is inside the repository root
• Uses the .md extension

Each rule file is capped at 12,000 characters, so keep the rule focused. Restart Cascade to force it to reload project rules.

Cascade adds an access token

Do not put tokens in a committed rules file.

Your rule should explicitly state that the machine is already authenticated with:

apidog login

If Cascade still tries to add a token, reinforce that instruction and have it use the existing authenticated CLI session.

See the Apidog CLI authentication guide.

Cascade invents a CLI flag

If the command fails with an “unknown option” error, tell Cascade to inspect the installed CLI version:

apidog run --help

Then update the rule with the supported command syntax.

Cascade reports success after a failed run

Use the exit code, not the summary text.

If the command exits non-zero, the scenario failed and should be treated as a failed gate.

From agent assistance to a tested loop

The setup is small:

1. Install apidog-cli.
2. Authenticate with apidog login.
3. Add the generated apidog run command to .windsurf/rules/apidog.md.
4. Tell Cascade to run the scenario after API changes.
5. Validate the terminal output and exit code.

Your API tests no longer depend on someone opening a GUI and clicking Run. You continue building scenarios visually in Apidog, while Cascade can execute the same scenarios as part of its local development loop.

When the command works locally, use it in CI as well. See Apidog CLI in GitHub Actions for secrets, reporters, and exit-code gating.

Download Apidog, create a scenario, add its generated command to a Windsurf rule, and let Cascade run it on the next API change.