How to Use the Apidog CLI in Claude Code

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.

Try Apidog today

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 setup that a generic install guide skips: the exact line for your CLAUDE.md, how Claude Code runs apidog run under its permission model, and how to use the result in its 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 first run with the agent doing the typing. This article assumes apidog --version prints a version 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 repository and get an interactive agent that proposes edits and command runs, you are in the right place.

The commands you want Claude Code to run belong in your Claude Code slash commands and its rules file. For persistent API test instructions, use CLAUDE.md.

The distinction matters because CLAUDE.md turns a one-off “run my tests” request into a project rule Claude Code can use in every session.

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. Anthropic’s docs note that Claude Code reads CLAUDE.md, not AGENTS.md, though you can import an existing AGENTS.md with @AGENTS.md.

If you already configured the Apidog CLI in Codex, the approach is the same with a different filename.

Create CLAUDE.md at your repository root. Claude Code also accepts ./.claude/CLAUDE.md, while ~/.claude/CLAUDE.md can hold personal global defaults.

Claude Code walks up the directory tree from the directory where you launch it and loads each CLAUDE.md it finds. A root-level file therefore applies to every session in the repository.

Add a 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.

Replace <scenario_id> and <env_id> with the IDs generated by Apidog.

Use CLAUDE.md instead of a chat instruction because chat context is temporary. A command in CLAUDE.md is available to every teammate and every Claude Code session. Claude Code loads the file at startup, and the instruction remains available after /compact.

Step 2: Get the command from Apidog

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

1. Open the test scenario in Apidog.
2. Open the CI/CD tab.
3. Copy the generated apidog run ... command.
4. Paste its scenario ID and environment ID into your CLAUDE.md block.

The generated command already includes the correct scenario ID, environment ID, and -r cli reporter.

The -r cli reporter prints step-by-step output and a summary in the terminal. This is the output Claude Code reads when deciding whether to continue or fix the implementation.

For flag details, see the complete Apidog CLI guide and the apidog run command reference.

Step 3: Have Claude Code run the test

Start Claude Code from your repository:

claude

Claude Code loads CLAUDE.md at startup, so it knows the Apidog CLI command before you ask it to make changes.

Make a change that touches your API, or explicitly ask Claude Code to run the API check. It should execute the apidog run command defined in CLAUDE.md.

Configure command permissions

In the default permission mode, Claude Code asks before running shell commands that have not been approved. Approve the apidog run command when prompted.

To allow a trusted command without repeated prompts:

• Run /permissions in a Claude Code session, or
• Add an allow rule in .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(apidog run *)"]
  }
}

A read-only test scenario against staging is a reasonable command to allowlist.

For unattended execution, Claude Code provides --dangerously-skip-permissions, which skips prompts entirely. Reserve that option for CI rather than daily local use.

Do not rely only on Claude Code saying that tests passed. Confirm that it shows:

• The literal apidog run ... command
• The CLI output
• The exit code

Step 4: Read the report inside Claude Code

When a run fails, use the CLI output as the debugging input.

With -r cli, Claude Code can see:

• Each request
• Each assertion
• The assertion that failed
• Expected and actual values
• Status-code mismatches

That output is often enough for Claude Code to locate the affected handler, schema field, or response value and attempt a fix.

For a browser-readable 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 in the reporter list. Claude Code needs inline terminal output to use the result in its next decision.

For JUnit output and other reporter formats, see Apidog CLI test reports.

Claude Code testing inside its own loop

The important behavior is what happens after the command becomes a project rule.

For example, Claude Code updates a handler that builds a checkout response:

1. It edits the implementation.
2. It runs the Apidog scenario against staging.
3. It reads the CLI output and exit code.
4. If the command exits with 0, it proceeds.
5. If the command exits non-zero, it inspects the failing assertion.
6. It changes the implementation and runs the scenario again.

The API test becomes part of the same edit-test-fix loop Claude Code already uses for unit tests.

You still author and maintain scenarios visually in Apidog. Claude Code runs the scenario and interprets the result, while you verify that it is using the command and exit code correctly.

For the broader workflow, see how to use AI agents for API testing and the Apidog AI test harness.

Verify Claude Code is actually running the CLI

Agents can report success they did not earn. Use these checks.

1. Confirm the command ran

Claude Code shows executed commands and their output inline.

Look for:

apidog run ...

Then verify there is CLI output directly below it.

If Claude Code says it ran tests but you cannot find the command, ask it to run the command again and show the raw output.

2. Confirm the exit code

Ask directly:

What was the exit code of that apidog run command?

apidog run exits with:

• 0 when every assertion passes
• A non-zero code when any assertion fails

Treat the exit code as the gate. If Claude Code says “tests passed” while the command returned non-zero, trust the exit code.

3. Confirm it used the real scenario

If the command fails with “scenario not found,” Claude Code may have used an incorrect or invented ID.

Check the -t and -e values against:

• Your CLAUDE.md
• The command generated in Apidog’s CI/CD tab

The IDs in CLAUDE.md should match the generated Apidog command exactly.

Optional: connect the Apidog MCP server

Running apidog run from CLAUDE.md covers the test execution workflow. To give Claude Code API context while it writes code, connect an MCP server as well.

Claude Code supports the Model Context Protocol. Add a server with claude mcp add ..., or commit a .mcp.json file at the project root and use --scope project so the team shares the configuration.

The Apidog MCP server exposes API specifications over MCP, allowing Claude Code to read the schema as it writes code.

Use the two integrations for different jobs:

• Apidog CLI: runs API test scenarios
• Apidog MCP server: provides API specification context

When Claude Code gets it wrong

It ignores the CLAUDE.md block

If Claude Code runs a generic command or no command, confirm that the rules file is being loaded.

• Ensure the filename is exactly CLAUDE.md.
• Place it at the repository root or a parent directory of your current working directory.
• Run /memory inside Claude Code to list loaded memory files.
• Restart the session after changing CLAUDE.md.

If the file is not listed by /memory, Claude Code cannot use its instructions.

It passes an access token anyway

If Claude Code adds --access-token, it may be guessing from public examples.

Keep this instruction in CLAUDE.md:

The machine is already authenticated via `apidog login`.
Never add an `--access-token` flag and never put a token in this file.

Never commit a real token to CLAUDE.md.

For one-time machine authentication, see Apidog CLI authentication.

It invents a flag

An “unknown option” error usually means Claude Code guessed a flag that your installed CLI version does not support.

Have it run:

apidog run --help

Then use the exact syntax reported by that installed version.

It reports a pass on a failed run

When the summary and exit code disagree, the exit code wins.

Keep that rule in CLAUDE.md, and require Claude Code to show the command output and exit code when it reports a result.

From a daily agent to a tested loop

The setup is small:

1. Install apidog-cli using the install guide.
2. Copy the generated apidog run command from your Apidog scenario.
3. Add it to your repository’s CLAUDE.md.
4. Let Claude Code run the scenario after API-related changes.
5. Verify the command output and exit code.

A broken endpoint can then be caught while Claude Code is still working on the change, rather than after deployment.

A test behind a GUI runs when someone clicks it. A command in CLAUDE.md can run whenever Claude Code needs verification. Keep building scenarios visually in Apidog, then let your agent execute them from the terminal.

Download Apidog, build a scenario, add its apidog run command to CLAUDE.md, and start a new Claude Code session.

When you are ready to run the same command in a pipeline without Claude Code, see Apidog CLI in GitHub Actions for secrets, reporters, and exit-code gating.