How to Use the Apidog CLI in Trae

Trae’s Builder agent can read your repository, edit files, run terminal commands, and use command output to decide what to do next. API tests should be part of that same loop. With apidog-cli, Builder can run Apidog test scenarios from the terminal, inspect the exit code, and use failures as feedback while it works.

Try Apidog today

The setup is a small project rules file. Once the CLI is installed and authenticated, Builder can run an Apidog scenario just like it runs unit tests: execute the command, read the result, and treat a non-zero exit code as a failure.

Before continuing, confirm that:

apidog --version

prints a version number and that your Apidog account is authenticated. For installation, authentication, and a first run, follow How to install the Apidog CLI with an AI coding agent.

Which Trae this is about

This article covers ByteDance’s desktop Trae IDE: the VS Code-based editor with a chat panel and the Builder agent mode. See Trae’s official site for product details.

It does not cover the standalone trae-agent GitHub research project. If you can open Trae, see the chat panel, and switch the agent to Builder, this workflow applies to you.

Trae can load project rules before Builder starts working. That makes API-test execution persistent instead of relying on a one-off chat prompt. For a Trae-independent overview, see the complete Apidog CLI guide.

Step 1: Add a Trae project rules file

Trae project rules live at:

.trae/rules/project_rules.md

Create that file at the repository root. According to Trae’s rules documentation, Builder loads these rules during initialization and uses them while generating and editing code.

Add a rule that tells Builder:

• when API tests are required;
• which Apidog command to run;
• how to interpret the exit code;
• how to handle authentication and unknown flags.

## API testing with the Apidog CLI

When you change code that touches an API endpoint, verify it by running the
Apidog test scenario, not just the unit tests.

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

Rules:
- `apidog run` exits 0 when every assertion passes and non-zero on any failure.
  Treat a non-zero exit code as a failing test, even if the summary looks fine.
- This 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.

Commit this file with the repository. Unlike a scenario ID pasted into chat, project rules remain available for every teammate and every future Builder session.

For monorepos, Trae can also read .trae/rules/ folders in subdirectories, allowing each service to keep its own API test command close to its code.

Step 2: Copy the real scenario command from Apidog

Do not manually guess scenario or environment IDs.

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

For example:

Command:
  apidog run -t your_scenario_id -e your_environment_id -r cli

Using the generated command avoids errors caused by invented or stale IDs. For available options, see the apidog run command reference.

Step 3: Run the scenario with Builder

Switch Trae to Builder mode and open your repository. Builder loads project_rules.md during initialization.

After changing API-related code, ask Builder to run the check:

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

Builder should use the command from your rules file:

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

Trae requires approval before Builder executes shell commands. Review the proposed command and click Run. Once it completes, Builder can read the terminal output and use the result in its next step.

The -r cli reporter is useful for agent workflows because it prints request-by-request results and a summary directly in the terminal.

Step 4: Read failures in the terminal

When a scenario fails, -r cli provides Builder with:

• each request that ran;
• each assertion;
• expected and actual values for failures;
• the final exit code.

This gives Builder concrete debugging context. For example, a failed assertion can identify a wrong status code, a missing response field, or an unexpected value.

To also generate a browser-friendly report, add the HTML reporter:

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

Keep cli enabled so Builder can still read inline terminal output. The html reporter writes a self-contained report to:

./apidog-reports

For JSON, JUnit, and other report formats, see the guide to Apidog CLI test reports.

Put API tests inside Builder’s edit-test-fix loop

The goal is not just running a command manually. The goal is making API validation part of Builder’s normal workflow.

For example, when Builder edits a checkout handler, the loop becomes:

1. Edit the handler.
2. Run the Apidog scenario against the configured environment.
3. Read the exit code and failed assertions.
4. Fix the implementation if the run fails.
5. Re-run the scenario.
6. Continue only after the scenario passes.

A green run lets Builder move on. A red run gives it request and assertion details to investigate. Your API scenario becomes a test gate alongside unit tests.

You still author and maintain scenarios visually in Apidog, while Builder executes them from the repository workflow. For more on this pattern, see how to use AI agents for API testing and the Apidog AI test harness.

Verify that Trae actually ran the CLI

Do not rely only on Builder’s summary. Verify the command and its result.

1. Check that apidog run appears in the terminal

Trae shows the commands Builder executed and their output. Look for the literal apidog run command and its resulting output.

If Builder claims it ran tests but no command appears in the terminal, ask it to run the scenario again and show the raw output.

2. Check the exit code

Ask:

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 source of truth. If Builder says “tests passed” but the process exited non-zero, the test failed.

3. Verify the scenario and environment IDs

If the CLI reports that a scenario cannot be found, Builder may be using an incorrect ID.

Compare the command in:

.trae/rules/project_rules.md

with the command generated in Apidog’s CI/CD tab. Verify both:

-t <scenario_id>
-e <environment_id>

The IDs stored in your project rules should match the generated Apidog command.

Optional: Connect the Apidog MCP server

The CLI is enough for running API tests. An MCP server adds specification context while Builder writes code.

Trae agents can act as MCP clients. To connect a server:

1. Open Trae settings.
2. Go to the MCP tab.
3. Choose a marketplace server or select Add Manually.
4. Provide the server JSON configuration with command, args, and env.

See Trae’s guide to adding MCP servers for the configuration flow.

The Apidog MCP server exposes API specifications over MCP. This creates a useful separation:

• Apidog CLI runs test scenarios.
• Apidog MCP server gives Builder access to API specifications.

Troubleshooting common setup failures

Builder ignores the rules file

Confirm the path is exactly:

.trae/rules/project_rules.md

The directory must be named rules, not rule, and the file must be under the repository root. Restart the Builder session to force Trae to reload project rules.

Builder adds --access-token

If Builder tries to add an access token, it is likely copying a public example instead of following your rules.

Keep this instruction in project_rules.md:

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

Do not store real tokens in the repository. For interactive and CI authentication details, see Apidog CLI authentication.

Builder invents a CLI flag

An “unknown option” error means the installed CLI version does not support the flag Builder used.

Have it run:

apidog run --help

Then update the command or rule using the exact syntax reported by your installed version.

Builder reports success after a failed run

Always check the process exit code. If the terminal summary and exit code appear to disagree, treat the non-zero exit code as a failure.

That is why the exit-code rule belongs in project_rules.md.

From daily agent usage to a tested workflow

The implementation is straightforward:

1. Install and authenticate apidog-cli using the install guide.
2. Create .trae/rules/project_rules.md.
3. Paste the real apidog run scenario command from Apidog.
4. Require Builder to treat non-zero exit codes as failed tests.
5. Verify the command and exit code in Trae’s terminal.

Your API scenarios remain visual and maintainable in Apidog, while Builder can execute them during implementation.

Download Apidog, create a scenario, add its apidog run command to your project rules, and use it as part of Builder’s next API change. To run the same scenario in CI, see Apidog CLI in GitHub Actions.