How to Use the Apidog CLI in Antigravity

Antigravity is a loop: its agent edits files, runs terminal commands, reads output, and decides what to do next. Your API tests should be part of that loop too. Instead of leaving scenarios in the Apidog GUI until someone manually clicks Run, expose them through the apidog-cli package and let the agent execute them like any other test command.

Try Apidog today

The setup is one rules-file block. Once apidog-cli is installed and Antigravity knows the command, it can run an Apidog scenario, inspect its exit code, and iterate on failing code.

Before continuing, make sure the CLI is installed and authenticated:

apidog --version

If you still need setup help, follow How to install the Apidog CLI with an AI coding agent. This guide assumes apidog --version prints a version number and apidog login has already authenticated the machine.

Which Antigravity this is about

Antigravity is Google’s agentic development platform, built on Gemini 3, that launched in late 2025. Its Agent Manager can plan work, edit repository files, execute shell commands, and use a browser.

If you have started an Antigravity task and watched the agent run commands in its terminal, this workflow applies to you. For a broader introduction, see what Google Antigravity is and how to use it.

The key detail is that Antigravity can load project rules. Put your API test command in those rules, and the agent can use it consistently instead of relying on a one-off chat instruction.

Step 1: Add an Antigravity rules file

Antigravity recognizes a .agents/ directory at the workspace root. Google’s codelab on building autonomous developer pipelines in Antigravity shows workspace rules placed in .agents/rules/.

Create this file:

.agents/rules/apidog.md

Alternatively, Antigravity can read an AGENTS.md file at the workspace root. This is also the file Codex reads for the Apidog CLI. If your repository already uses AGENTS.md, keep the instruction there instead of duplicating it.

Add a short, explicit rule block:

## API testing with the Apidog CLI

- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed.
- A non-zero exit code means a failure: inspect the report and fix the code.
- This machine is already authenticated via `apidog login`.
- Never add an `--access-token` flag or put a token in this file.

Keep this instruction in the repository rather than in chat. Antigravity does not retain ad hoc coaching across sessions, but workspace rules are available to every new task and teammate.

Step 2: Copy the generated command from Apidog

Do not guess scenario or environment IDs.

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

It should look similar to this:

apidog run -t 123456 -e 789012 -r cli

The flags are:

• -t: test scenario ID
• -e: environment ID
• -r cli: print results directly in the terminal

Paste the real command into .agents/rules/apidog.md or AGENTS.md. This gives Antigravity a stable, exact command to run.

For the available options, see the apidog run command reference.

Step 3: Ask Antigravity to run the scenario

Start an Antigravity task after adding the rules file. The agent loads the project rules when it begins.

You can explicitly request the check:

Run the Apidog test scenario and tell me the exit code.

The agent should execute the apidog run command from your rules file in its terminal.

Whether Antigravity asks for approval depends on its Security Preset. Google describes these terminal and file-access controls in its getting started with Antigravity codelab.

If Antigravity requests approval, review the command before allowing it to run. A read-only test scenario against staging is usually an appropriate in-workspace command to approve.

The important outcome is not a summary such as “tests passed.” You want to see:

• the literal apidog run ... command;
• the CLI output;
• the final exit code.

Step 4: Read failures from the terminal report

With -r cli, Apidog prints a readable test result directly in the terminal. Antigravity can inspect:

• requests that ran;
• assertions that passed or failed;
• expected and actual values;
• failing status codes or fields.

That output gives the agent enough context to locate the affected handler, request mapping, or response field and attempt a fix.

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

apidog run -t 123456 -e 789012 -r cli,html

The html reporter writes a self-contained report to:

./apidog-reports

Keep cli in the reporter list. Antigravity needs inline terminal output to evaluate the result and decide its next step.

For more report formats, including JUnit for CI systems, see the complete Apidog CLI guide and how to read Apidog CLI test reports.

Put API tests inside the agent loop

Once the command is in the rules file, API testing becomes part of the agent’s normal edit-test-fix cycle.

For example, an agent updates a checkout response handler:

1. It edits the handler.
2. It runs the Apidog scenario against staging.
3. It reads the exit code.
4. If the run is green, it continues.
5. If the run is red, it reads the failed assertion.
6. It fixes the response, status code, or missing field.
7. It runs the scenario again.

The API scenario now behaves like a unit-test gate, but it validates the real API behavior defined in Apidog.

This follows a delegate-then-verify workflow: Antigravity executes the command and interprets the result, while you continue authoring and maintaining scenarios visually in Apidog. For related patterns, see how to use AI agents for API testing and the Apidog AI test harness.

Verify Antigravity actually ran the CLI

Do not rely only on the agent’s prose summary. Verify the run in three steps.

1. Confirm the command was executed

Open Antigravity’s terminal output and look for the actual command:

apidog run ...

Then confirm that CLI output appears below it.

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

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 value when an assertion fails.

Treat the exit code as the source of truth. If the agent says “tests passed” but the command returned a non-zero exit code, the test run failed.

3. Confirm it used the correct scenario

If the CLI reports “scenario not found,” verify the IDs:

• Compare the -t scenario ID with the command generated in Apidog.
• Compare the -e environment ID with the selected Apidog environment.
• Confirm the same IDs are stored in your rules file.

The generated command from Apidog is the authoritative source.

Optional: Connect the Apidog MCP server

The CLI is enough to run scenarios. Add MCP when you also want the agent to access API specifications while it writes code.

Antigravity supports the Model Context Protocol. According to Google’s getting started codelab, configure MCP servers in:

$HOME/.gemini/config/mcp_config.json

Add your server under the mcpServers object with its command, args, and env, then refresh MCP from Antigravity settings.

The Apidog MCP server exposes API specifications through MCP. Use the two integrations for different purposes:

• Apidog CLI: run scenarios and enforce pass/fail results.
• Apidog MCP server: provide API schema context while the agent writes code.

Troubleshooting common setup failures

Antigravity ignores the rules file

If the agent uses a generic command or does not run a test:

1. Confirm the file name and location.
2. Use .agents/rules/apidog.md at the workspace root, or use root-level AGENTS.md.
3. Start a fresh task so Antigravity reloads project rules.

The agent adds --access-token

The agent may infer this from public examples. Your rules should explicitly state that the machine is authenticated through:

apidog login

Do not store a token in AGENTS.md or .agents/rules/apidog.md.

For authentication details, see Apidog CLI authentication.

The agent invents a CLI flag

If the CLI returns an “unknown option” error, have the agent check the locally installed version:

apidog run --help

Use the flags printed by that command rather than a guessed flag.

The agent reports success after a failed run

When the summary conflicts with the command result, the exit code wins. Keep the exit-code rule in your workspace instructions and require the agent to report it after every run.

From a daily agent to a tested loop

Install apidog-cli once using the installation guide, then add the generated apidog run command to your Antigravity rules file.

From that point, Antigravity has a repeatable API test command it can run while changing code:

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

A test behind a GUI runs only when a person remembers to click it. A CLI command in the agent’s rules can run whenever Antigravity needs to verify an API change.

Build scenarios visually in Apidog, add the generated command to your rules file, and let the agent use it on the next API change. To run the same command in CI without an agent, see Apidog CLI in GitHub Actions.