How to Use the Apidog CLI in GitHub Copilot

GitHub Copilot’s agent mode is 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 only when someone remembers to click them. Copilot never touches them.

Try Apidog today

The fix is one configuration file. The Apidog CLI is an npm package, apidog-cli, that runs test scenarios you built in Apidog directly from a terminal. Once the CLI is installed and Copilot knows it exists, agent mode can run an Apidog scenario like any other test: execute the command, inspect the exit code, and fix the code when the result is red.

Before continuing, install and authenticate the CLI. How to install the Apidog CLI with an AI coding agent covers npm installation, login, and a first run. This guide assumes the following command prints a version number:

apidog --version

It also assumes your Apidog account is authenticated.

Which Copilot this applies to

GitHub Copilot includes several products with overlapping names. This guide targets the Copilot experiences that can execute shell commands.

The primary target is Agent mode in VS Code. Open Copilot Chat, select Agent from the mode dropdown, and Copilot can edit files, run terminal commands, inspect output, and iterate on a task. It asks for confirmation before running commands, which is where apidog run fits into the workflow.

Two related surfaces are worth distinguishing:

• Copilot coding agent runs asynchronously in GitHub Actions after you assign it an issue. It creates a pull request rather than working in your editor.
• Copilot CLI is a separate terminal client.

Both can run commands, but VS Code Agent mode provides the shortest edit-test-fix loop. The repository instructions below also work with the Copilot coding agent because it reads the same instructions file. For more context, see GitHub Copilot’s new coding agent.

The key is to give Copilot a persistent project rule instead of repeatedly telling it to run API tests in chat.

Step 1: Add Apidog rules to Copilot instructions

Copilot loads repository instructions from .github/copilot-instructions.md at the root of your repository. Agent mode, Copilot Chat, code review, and the coding agent load this file automatically, according to the GitHub documentation on repository custom instructions.

Create the file:

mkdir -p .github
touch .github/copilot-instructions.md

Then add an Apidog testing rule:

## API testing with the Apidog CLI

When you change an API endpoint, verify it with the Apidog CLI before
declaring the task done. Run:

    apidog run -t 812345 -e 671234 -r cli

- `apidog run` exits 0 when every assertion passes, non-zero on any failure.
  Treat a non-zero exit as a failing test, even if the summary text looks fine.
- The machine is already authenticated via `apidog login`. Do NOT add an
  `--access-token` flag and never put a token in this file.
- If you hit an "unknown option" error, run `apidog run --help` and use the
  real flags. Do not guess.

Replace the -t and -e values with your actual scenario and environment IDs.

Put this instruction in the repository file rather than chat. A scenario ID mentioned in chat disappears with the session; an instruction in .github/copilot-instructions.md applies to every teammate, every Agent mode session, and every coding-agent pull request.

If the rule should apply only to a subset of files, GitHub also supports path-specific instructions in .github/instructions/NAME.instructions.md. For this use case, one repository-wide file is usually enough.

Step 2: Copy the command from Apidog

Do not manually construct the apidog run command. Apidog generates it.

1. Open your test scenario in Apidog.
2. Open the CI/CD tab.
3. Copy the generated command.

The command includes the correct scenario ID (-t), environment ID (-e), and reporter:

apidog run -t 812345 -e 671234 -r cli

Paste that exact command into .github/copilot-instructions.md.

The values generated in Apidog are the source of truth. If your instructions file and the scenario’s CI/CD tab differ, update the instructions file to match Apidog. For available flags and reporters, see the apidog run command reference.

Step 3: Run the scenario from Agent mode

Open Copilot Chat in VS Code and switch to Agent mode. Because it loads .github/copilot-instructions.md, Copilot already has the command and the expected behavior.

After changing an API endpoint, ask Copilot:

Run the Apidog API test scenario and tell me the result.

Copilot should issue the apidog run command from your instructions file. Agent mode displays the command and requests approval before execution.

Approve the command. With the cli reporter, the integrated terminal shows each request, assertion, and the final result.

Verify that Copilot reports both:

1. The test summary.
2. The process exit code.

VS Code can remember your approval for a command in the workspace. For a read-only scenario against staging, allowing the known apidog run command can reduce repeated approval prompts.

Step 4: Read failures and add HTML reports

When a scenario fails, the CLI output provides the data Copilot needs for the next iteration. The cli reporter shows each request, assertion, expected value, and actual value.

For a browser-readable report, add the HTML reporter:

apidog run -t 812345 -e 671234 -r cli,html

The html reporter writes a self-contained report to ./apidog-reports.

Keep cli in the reporter list. Copilot reads terminal output to decide whether to continue, fix code, or stop. The HTML report is useful for manual review and sharing results with teammates.

For other formats, including JUnit output for CI dashboards, see the complete Apidog CLI guide and how to read Apidog CLI test reports.

Put API tests inside Copilot’s loop

Once the instruction is in place, Copilot can treat API scenarios as part of its normal workflow.

For example, when Agent mode changes a checkout handler:

1. It edits the handler.
2. It runs the Apidog scenario against staging.
3. It reads the terminal output and exit code.
4. If the result is green, it continues.
5. If the result is red, it identifies the failed assertion, updates the code, and runs the scenario again.

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

You still author and maintain scenarios visually in Apidog. Copilot runs them and interprets the result, while you verify that it is using the real command and honoring the exit code. For the broader workflow, see how to use AI agents for API testing and the Apidog AI test harness.

Verify that Copilot actually ran the CLI

Do not rely only on an agent’s summary. Use these checks.

1. Confirm the command executed

Agent mode shows executed commands and their output in the terminal. Look for the literal apidog run ... command followed by its output.

If Copilot claims it ran tests but you cannot find the command, ask it to run the scenario again and show the raw output.

2. Confirm the exit code

Ask:

What was the exit code of that apidog run command?

apidog run exits with:

• 0 when all assertions pass
• A non-zero value when any assertion fails

Treat a non-zero exit code as a failed test, even when Copilot’s prose says the tests passed.

3. Confirm it used the correct scenario

If the CLI returns “scenario not found,” Copilot may have used an invented or outdated ID.

Compare the -t and -e values in:

• .github/copilot-instructions.md
• The command generated on the Apidog scenario’s CI/CD tab

The IDs generated by Apidog are authoritative.

Optional: Connect the Apidog MCP server

The CLI covers test execution. If you also want Copilot to read your API specification while writing code, connect the Apidog MCP server.

VS Code Agent mode reads workspace MCP configuration from .vscode/mcp.json, according to the GitHub documentation on extending Copilot Chat with MCP.

The Apidog MCP server exposes API specifications over MCP. This creates a clear split:

• Apidog CLI runs scenarios and returns test results.
• Apidog MCP server provides API schema context while Copilot writes code.

If you use the Copilot coding agent in GitHub Actions, MCP configuration lives in repository settings under the Copilot section for Cloud agent. Store secrets as Actions secrets prefixed with COPILOT_MCP_. The .vscode/mcp.json file is specifically for VS Code Agent mode.

Common setup failures

Copilot ignores the instructions file

Check all of the following:

• The file is named exactly .github/copilot-instructions.md.
• The .github directory is at the repository root.
• Custom instructions are enabled in VS Code settings.

A wrong path means Copilot will not load the file.

Copilot adds an access token

If Copilot tries to add --access-token, it is likely copying a public example. Keep the instruction that the machine is already authenticated through apidog login.

Never store a real token in .github/copilot-instructions.md. For authentication details, see Apidog CLI authentication.

Copilot invents a CLI flag

An “unknown option” error means the agent guessed a flag that your installed CLI version does not support.

Run:

apidog run --help

Then use the exact flag shown by your installed version.

Copilot reports success after a failed run

Always use the exit code as the test gate.

If the CLI output or exit code indicates failure, the scenario failed. The agent’s natural-language summary does not override the process result.

From a daily agent to a tested loop

The setup is small:

1. Install apidog-cli using the installation guide.
2. Add the generated apidog run command to .github/copilot-instructions.md.
3. Require a zero exit code before Copilot declares API work complete.

A test behind a GUI runs when a person remembers to click it. A CLI command can run whenever Copilot modifies an endpoint.

Continue building scenarios visually in Apidog, then add the generated command to your repository instructions. When you are ready to use the same command outside Copilot, see Apidog CLI in GitHub Actions for secrets, reporters, and exit-code gating.

Download Apidog, create a scenario, and make it part of your agent’s normal test loop.