Claude Code is a loop: it edits files, runs commands in your terminal, 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. Your agent 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 Claude Code knows it exists, your agent runs an Apidog scenario the same way it runs your unit tests: fire the command, read the exit code, fix the code if it is red.
This guide covers the Claude Code specific part the generic install guide skips: the exact line for your CLAUDE.md, how Claude Code runs apidog run under its permission model, and how to read the result inside its own edit-test-fix loop.
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 and the first run, with the agent doing the typing. This article assumes apidog --version prints a number and your Apidog account is authenticated.
Which Claude Code this is about
This is the Claude Code CLI, Anthropic’s coding agent that runs in your terminal (or desktop app). It reads your repository, edits files, and runs shell commands, asking for approval based on your permission mode. It is not the Claude chat app and not a plain API call. If you run claude in a repo and get an interactive agent that proposes edits and command runs, you are in the right place. The commands you write for the terminal live in your Claude Code slash commands and its rules file, and that rules file is where the Apidog CLI belongs.
The distinction matters because Claude Code has its own way of learning project rules, and that mechanism turns a one-off “run my tests” into something Claude reaches for on its own. That mechanism is CLAUDE.md.
Step 1: Add the Apidog block to CLAUDE.md
Claude Code reads CLAUDE.md files at the start of every session. This is the direct counterpart to AGENTS.md for Codex; in fact Anthropic’s docs note that Claude Code reads CLAUDE.md, not AGENTS.md, and suggest importing an existing AGENTS.md with @AGENTS.md if you keep one for another agent. If you already set up the Apidog CLI in Codex, this is the same idea with a different filename.
Put a CLAUDE.md at your repository root (Claude Code also accepts ./.claude/CLAUDE.md, and a global ~/.claude/CLAUDE.md for personal defaults). Claude Code walks up the directory tree from where you launched it and loads every CLAUDE.md it finds, so one file at the repo root reaches every session. Add a short block like this:
## API testing with Apidog CLI
This project has Apidog test scenarios. To check the API, run:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- Exit code 0 means every assertion passed. Non-zero means something failed; open the report and fix it before moving on.
- The machine is already authenticated via `apidog login`. Never add an `--access-token` flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
This is why you write the CLI into CLAUDE.md instead of mentioning it in chat. A scenario ID typed into a session is gone when that session ends. One in CLAUDE.md is there for every teammate and every Claude Code run from now on. The file is loaded in full at launch and survives a /compact, so the instruction stays live for the whole session.
Step 2: Get the command from Apidog
The <scenario_id> and <env_id> in that block are not values you guess. Open your test scenario in Apidog, go to the CI/CD tab, and copy the generated apidog run ... command. It already has the real scenario ID, the environment ID, and the -r cli reporter filled in. Paste those exact IDs into your CLAUDE.md block.
The -r cli reporter prints a step-by-step result and a summary right in the terminal, which is exactly the output Claude Code reads to decide its next step. For a full breakdown of every flag, see the complete Apidog CLI guide and the apidog run command reference.
Step 3: Have Claude Code run the test
With the block in place, start Claude Code in your repo:
claude
Claude Code loads CLAUDE.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. Claude Code issues the apidog run command from your CLAUDE.md.
Here the permission model matters. In its default mode, Claude Code asks before it runs a shell command it has not seen approved. Approve the apidog run command when it prompts. To stop being asked for a command you trust, add a permission rule so the CLI runs without a prompt: run /permissions inside the session, or add an allow rule for Bash(apidog run *) in .claude/settings.json. A read-only test scenario against staging is a safe command to allowlist. For unattended runs there is --dangerously-skip-permissions, which skips prompts entirely; save that for CI, not your daily driver.
You want to see the run executing and Claude Code reporting back both the summary and the exit code, not just a sentence claiming success.
Step 4: Read the report inside Claude Code
When a run goes red, the report has the answer. With -r cli, Claude Code gets a readable breakdown in the 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 Claude Code to find the fix.
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 Claude Code still gets the inline output it reads to decide its next step. For the JUnit format CI dashboards parse and the other reporters, see Apidog CLI test reports.
Claude Code testing inside its own loop
The point is what happens when you stop asking and Claude Code runs the scenario on its own because CLAUDE.md told it to.
Picture Claude Code 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 Claude Code already runs your unit tests through. You wrote one instruction and Claude folded the command into how it already works.
This is the delegate-then-verify model that makes any agent workflow safe. Claude Code 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 Claude Code is actually running the CLI
Agents report success they did not earn, and Claude Code is no exception. Three checks, in order of how often they catch problems.
First, confirm the command ran at all. Claude Code shows the commands it executed and their output inline. Look for the literal apidog run ... line and a result under it. If Claude 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 Claude Code, or a pipeline, treat the run as a clean gate. When Claude’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,” Claude may have invented or misremembered an ID. Re-check the -t and -e values against CLAUDE.md and the command Apidog generated in the CI/CD tab. The IDs in CLAUDE.md are the truth.
Optional: connect the Apidog MCP server
Running apidog run from CLAUDE.md covers most of what you need. To go one step further, connect an MCP server so Claude Code can read your API spec while it writes code, not just test after the fact.
Claude Code supports the Model Context Protocol. You add a server with claude mcp add ... or by committing a .mcp.json file at your project root and choosing --scope project so the whole team gets it. The Apidog MCP server exposes your API specifications over MCP, so Claude reads your schema as it codes. Think of it as division of labor: the CLI runs the tests, MCP feeds the agent the spec.
When Claude Code gets it wrong
A few failures show up often during setup.
It ignores the CLAUDE.md block. If Claude runs a generic command or none at all, the block may not be loading. Confirm the file is named exactly CLAUDE.md and sits at your repo root or a parent of your current directory. Run /memory inside the session to list the files Claude actually loaded; if yours is not there, Claude cannot see it. Restarting the session forces a fresh read.
It passes an access token anyway. If Claude tries to add --access-token, it is guessing from public examples. The block already tells it not to, since the machine is authenticated via apidog login. Reinforce the line, and never put a real token in CLAUDE.md. For how the machine authenticates once, see Apidog CLI authentication.
It invents a flag. An “unknown option” error means Claude 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 your CLAUDE.md 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 block to your repo’s CLAUDE.md, and Claude Code 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 Claude 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 Claude decides to. You keep building scenarios visually in Apidog, and your agent runs them where you are not watching. Download Apidog, build one scenario, drop its apidog run command into CLAUDE.md, and watch Claude pick it up on the next change. When you are ready to run the same command in a pipeline without Claude present, Apidog CLI in GitHub Actions covers the secrets, reporters, and exit-code gating.
