Windsurf’s Cascade agent runs a loop: it edits files, runs terminal commands, reads the output, and decides what to do next. So why aren’t your API tests in that loop? They sit in Apidog behind a GUI and run when someone remembers to click. Cascade never touches them.
The fix is one config block. The Apidog CLI is an npm package, apidog-cli, that runs the test scenarios you built in Apidog straight from a terminal. Once the CLI is installed and Cascade knows it exists, Windsurf runs an Apidog scenario the same way it runs your unit tests: fire the command, read the exit code, fix the code if it comes back red.
If you have not installed the CLI yet, do that first. How to install the Apidog CLI with an AI coding agent walks through the npm install, authentication, and the first run, with an agent doing the typing. This article assumes apidog --version prints a number and your Apidog account is authenticated.
Which Windsurf this is about
Windsurf is Codeium’s agentic IDE, and its built-in agent is called Cascade. Cascade runs locally, reads your repository, edits files, and executes shell commands in your integrated terminal, asking for approval based on your auto-execution setting. This is the editor and its agent, not a browser extension or an autocomplete plugin.
If you have not set it up yet, start with how to download and install Windsurf. Once Cascade is open in your project, you can teach it about the Apidog CLI through its own rules mechanism, which turns a one-off “run my tests” into something Cascade reaches for on its own.
Step 1: Add an Apidog rule to .windsurf/rules
Cascade reads project rules from Markdown files before it starts working. Put them in a .windsurf/rules/ directory at your repository root, one rule per file. Windsurf still reads a legacy single-file .windsurfrules at the workspace root, and a global ~/.codeium/windsurf/memories/global_rules.md that applies to every project, but for a per-project instruction the .windsurf/rules/ directory is the right home. This is documented in Windsurf’s rules and memories reference.
Create .windsurf/rules/apidog.md with a block like this:
# 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.
Why a rule file instead of a chat message? A scenario ID typed into chat is gone when the session ends. One in .windsurf/rules/apidog.md is there for every teammate and every Cascade session from now on. It persists, it is versioned in Git, and Cascade loads it into context automatically at startup.
Step 2: Get the command from Apidog
The <scenario_id> and <env_id> in that block are not placeholders you guess. Apidog generates the exact command for you.
Open the test scenario in Apidog, go to its CI/CD tab, and copy the ready-made apidog run command. It already has the correct scenario ID, environment ID, and reporter flags filled in. Paste that command into your .windsurf/rules/apidog.md in place of the example line. Now the rule holds a command that actually works against your project, not a template.
For the full anatomy of that command and every flag it accepts, see the apidog run command reference.
Step 3: Have Cascade run the test
With the rule in place, open Cascade in your repo. It loads .windsurf/rules/apidog.md as it starts, so it already knows the CLI is there. Make a change that touches your API, or just ask it to run the check:
Run the Apidog scenario and tell me the exit code.
Cascade issues the apidog run command from your rule. Whether it runs without a prompt depends on your auto-execution setting. Windsurf offers four levels: Disabled (every command needs approval), Allowlist Only (only commands matching your allowlist auto-run), Auto (a premium-model judgment call), and Turbo (everything auto-runs except denylisted commands). In Turbo mode a plain apidog run executes on its own; in the stricter modes Cascade pauses and asks first.
If you want apidog run to auto-execute without loosening everything, add it to your allowlist. The setting is windsurf.cascadeCommandsAllowList, reachable from the Command Palette under Open Settings; add apidog and Cascade runs the command without asking. The matching denylist setting is windsurf.cascadeCommandsDenyList, and the denylist wins when a command matches both. Both are covered in Windsurf’s terminal documentation. A read-only scenario against staging is exactly the kind of safe, in-workspace command an allowlist entry is built for.
Step 4: Read the report inside Windsurf
When a run goes red, the report has the answer. The -r cli reporter prints a step-by-step result and summary right in Cascade’s terminal: each request, each assertion, and which one failed with expected versus actual value. The failing assertion names the exact field or status code, which is usually enough for Cascade to find the fix on its next pass.
For a report you can open in a browser or hand to a teammate, add the HTML reporter:
apidog run -t <scenario_id> -e <env_id> -r cli,html
The html reporter writes a self-contained file to ./apidog-reports. Keep cli in the list so Cascade still gets the inline output it reads to decide its next step. For every reporter, including the JUnit format CI dashboards parse, see the complete Apidog CLI guide and how to read Apidog CLI test reports.
Windsurf testing inside its own loop
The point is what happens when you stop asking and Cascade runs the scenario on its own because the rule told it to.
Picture Cascade editing a handler that builds a checkout response. Its loop changes. It edits the code, then, instead of declaring victory, runs your Apidog scenario against staging, reads the exit code, and acts on it. Green, it moves on. Red, it opens the report, reads which assertion failed (the status code, the missing field, the wrong value), tries a fix, and re-runs. The API test becomes part of the same edit-test-fix loop Cascade already runs your unit tests through. You wrote one rule and Cascade folded the command into how it already works.
This is the delegate-then-verify model that makes any agent workflow safe. Cascade runs the command and reads the result; you keep authoring scenarios visually in Apidog and spot-check that the agent reads exit codes honestly. For the broader pattern, see how to use AI agents for API testing and the Apidog AI test harness.
Verify Cascade is actually running the CLI
Agents report success they did not earn, and Cascade is no exception. Three checks, in order of how often they catch problems.
First, confirm the command ran at all. Cascade shows the commands it executes and their output inline in the terminal. Look for the literal apidog run ... line and a result under it. If Cascade says it ran the tests but you do not see the command, it summarized something it never did. Ask it to run again and show the raw output.
Second, confirm the exit code, the one that matters. Ask it directly:
What was the exit code of that apidog run command?
apidog run exits 0 when every assertion passes and non-zero when anything fails. That single behavior lets Cascade, or a pipeline, treat the run as a clean gate. When Cascade’s prose says “tests passed” but the exit code is non-zero, the exit code is right.
Third, confirm it used the real scenario. If a run fails with “scenario not found,” Cascade may have invented or misremembered an ID. Re-check the -t and -e values against your rule file and the command Apidog generated in the CI/CD tab. The IDs in .windsurf/rules/apidog.md are the truth.
Optional: connect the Apidog MCP server
Running apidog run from a rule covers most of what you need. To go one step further, connect an MCP server.
Cascade supports the Model Context Protocol. Windsurf reads its server list from ~/.codeium/windsurf/mcp_config.json, which you can edit directly or manage through the Cascade MCP panel; the format is documented in Windsurf’s MCP reference, and how to set up MCP servers in Windsurf walks through the panel. The Apidog MCP server exposes your API specifications over MCP, so Cascade can read your schema while it writes code, not just after the fact. The division of labor is clean: the CLI runs the tests, and MCP feeds the agent the spec.
When Windsurf gets it wrong
A few failures show up often during setup.
It ignores the rule. If Cascade runs a generic command or none at all, the rule may not be loading. Confirm the file lives in .windsurf/rules/ at your repository root and has a .md extension. Each rule file is capped at 12,000 characters, so keep the Apidog block short. Restarting Cascade forces a fresh read.
It passes an access token anyway. If Cascade tries to add an access token to the command, it is guessing from public examples. Your rule already tells it not to, since the machine is authenticated via apidog login. Reinforce the line, and never put a real token in a rules file that gets committed. For how authentication actually works, see the Apidog CLI authentication guide.
It invents a flag. An “unknown option” error means Cascade guessed a flag your version does not have. Tell it to run apidog run --help and copy the exact flag from there, which is always correct for your installed version.
It reports a pass on a failed run. The costliest one, and the reason the exit-code rule is in both your rule file and your verification step. When the summary and the exit code disagree, the exit code wins.
From a daily agent to a tested loop
That is the setup. Install apidog-cli once following the install guide, add a short Apidog rule to your repo’s .windsurf/rules/ directory, and Cascade knows how to run your API tests and read the result inside the same loop it already uses to edit code. A broken endpoint gets caught while Cascade is still working on the change, not after it ships.
A test behind a GUI runs when a human clicks; a one-line command runs whenever Cascade decides to. You keep building scenarios visually in Apidog, and your agent runs them where you are not watching. To run the same command in a pipeline once it works locally, Apidog CLI in GitHub Actions covers the secrets, reporters, and exit-code gating. Download Apidog, build one scenario, drop its apidog run command into a Windsurf rule, and watch Cascade pick it up on the next change.
