DEV Community

Cover image for How to Use the Apidog CLI in Codex
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Use the Apidog CLI in Codex

Codex edits files, runs commands, reads output, and decides what to do next. Your API tests should be part of that same loop. If your Apidog scenarios only run when someone clicks in the GUI, Codex cannot use them to validate the code it just changed.

Try Apidog today

The fix is to expose your Apidog scenario as a terminal command. The Apidog CLI is an npm package, apidog-cli, that runs test scenarios you built in Apidog from your shell. Once Codex knows the command, it can run API tests like unit tests: execute the command, read the exit code, inspect failures, and patch the code.

This guide focuses on the Codex-specific setup:

  • what to put in AGENTS.md
  • how to prompt Codex
  • how Codex runs apidog run inside its edit-test-fix loop
  • how to verify the result

If you have not installed the CLI yet, do that first. How to install the Apidog CLI with an AI coding agent covers the npm install, access token, and first run with Codex doing the typing. This article assumes apidog --version prints a version number and your Apidog account is authenticated.

Which Codex this is about

This applies to both OpenAI Codex CLI and Codex App: the local agent that reads your repository, edits files, and executes shell commands in a sandbox, asking for approval depending on your permission mode.

It is not the old Codex code-completion API.

If you run codex and get a full-screen interface with diffs and command output, you are in the right place. The OpenAI Codex CLI guide covers the basics.

The key Codex mechanism is AGENTS.md.

Use AGENTS.md, not a chat reminder

Codex reads AGENTS.md before it starts working. Treat it like project-level instructions for the agent.

Codex builds its instruction set by walking from your Git root down to your current directory and concatenating each AGENTS.md file root-first. More specific files can override broader ones. There is also a global file at:

~/.codex/AGENTS.md
Enter fullscreen mode Exit fullscreen mode

For this setup, a single repo-level file is enough:

touch AGENTS.md
Enter fullscreen mode Exit fullscreen mode

Put the Apidog command in AGENTS.md so Codex sees it every session. A scenario ID pasted into chat disappears when the session ends. A command in AGENTS.md is available to every teammate and every future Codex run.

Step 1: Add the Apidog run command to AGENTS.md

Get the exact apidog run command from Apidog’s CI/CD or CLI instructions for your scenario, then add it to AGENTS.md.

Use this structure:

## API test command

When a change touches API behavior, run the Apidog scenario before reporting success.

Use this command:
Enter fullscreen mode Exit fullscreen mode


bash
apidog run -r cli


Rules:

- Do not add `--access-token`; this machine is already authenticated with `apidog login`.
- Treat exit code `0` as pass.
- Treat any non-zero exit code as failure.
- If the run fails, read the CLI output, identify the failed request or assertion, fix the code, and rerun the command.
- Do not report the task as complete until the command exits `0`.
Enter fullscreen mode Exit fullscreen mode

Replace the placeholder with the real command Apidog generated for your scenario.

For example, your real command may include IDs such as -t and -e. Keep those exact values from Apidog. Do not ask Codex to invent them.

Step 2: Start Codex in your repo

Run Codex from the repository root or a subdirectory beneath the AGENTS.md file:

codex
Enter fullscreen mode Exit fullscreen mode

Codex loads AGENTS.md when the session starts. Now give it work that touches your API, or explicitly ask it to run the scenario:

Update the checkout response handler, then run the Apidog API test from AGENTS.md and fix any failures.
Enter fullscreen mode Exit fullscreen mode

Codex running Apidog CLI

Codex should issue the apidog run command from AGENTS.md.

In default Auto mode, Codex can read files, edit files, and run commands inside the working directory. A normal apidog run usually executes without a prompt. If your permission mode is Read-only, Codex pauses before running it. Approve the command or change the mode with:

/permissions
Enter fullscreen mode Exit fullscreen mode

Keep the cli reporter enabled:

-r cli
Enter fullscreen mode Exit fullscreen mode

That reporter prints request-by-request results and assertion failures directly in the terminal, which gives Codex the output it needs to decide what to fix next.

Step 3: Let Codex use Apidog in its own loop

The goal is not to manually ask Codex to run the test once. The goal is to make the Apidog scenario part of Codex’s normal workflow.

A useful loop looks like this:

  1. Codex edits a handler, controller, route, or schema.
  2. Codex runs your Apidog scenario.
  3. apidog run exits 0 or non-zero.
  4. If green, Codex continues.
  5. If red, Codex reads the failed assertion.
  6. Codex patches the implementation.
  7. Codex reruns the same scenario.

That turns your API test into the same kind of gate as a unit test.

This is the delegate-then-verify model for agent workflows: Codex runs the command and reads the result; you keep authoring scenarios visually in Apidog. For the broader pattern, see how to use AI agents for API testing and the Apidog AI test harness.

Verify Codex is actually running the CLI

Do not trust a summary without checking the command output.

1. Confirm the command ran

The Codex interface shows executed commands and output inline. Look for the literal command:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

If Codex says the tests passed but you do not see the command, ask it to rerun and show raw output:

Run the Apidog command again and show the raw CLI output.
Enter fullscreen mode Exit fullscreen mode

2. Confirm the exit code

Ask:

What was the exit code of that apidog run command?
Enter fullscreen mode Exit fullscreen mode

apidog run exits:

  • 0 when every assertion passes
  • non-zero when anything fails

That behavior lets Codex or CI treat the scenario as a gate.

If Codex says “tests passed” but the exit code is non-zero, trust the exit code.

Codex reporting Apidog CLI exit code

3. Confirm it used the real scenario

If the run fails with “scenario not found,” Codex may have used the wrong ID.

Check the command in AGENTS.md against the command Apidog generated in the CI/CD tab. The IDs in AGENTS.md should be treated as the source of truth.

Read the Apidog test report

When a run fails, the CLI output usually contains the fix path.

With:

-r cli
Enter fullscreen mode Exit fullscreen mode

Codex gets a readable breakdown:

  • each request
  • each assertion
  • expected value
  • actual value
  • failed status code or field

That is usually enough for Codex to locate the implementation issue.

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

Apidog HTML report

Use both reporters if Codex still needs inline output:

apidog run <PROJECT_OR_SCENARIO_ARGS> -r cli,html
Enter fullscreen mode Exit fullscreen mode

The html reporter writes a self-contained file to:

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Keep cli in the list so Codex can read the terminal output during its loop.

For all flags and reporters, including JUnit output for CI dashboards, see the complete Apidog CLI guide and the apidog run command reference.

Go deeper than shell commands

Running apidog run from AGENTS.md covers most workflows. Two integrations go further.

Option 1: Use MCP

Codex supports the Model Context Protocol. You can add MCP servers with:

codex mcp add
Enter fullscreen mode Exit fullscreen mode

Or by editing:

~/.codex/config.toml
Enter fullscreen mode Exit fullscreen mode

with an [mcp_servers.NAME] block.

The Apidog MCP server exposes your API specifications over MCP, so Codex can read your schema while it writes code.

Use both tools together:

  • MCP gives Codex the spec.
  • Apidog CLI runs the tests.

Option 2: Use codex exec

Interactive Codex starts with:

codex
Enter fullscreen mode Exit fullscreen mode

For scripts, use:

codex exec "..."
Enter fullscreen mode Exit fullscreen mode

codex exec runs Codex non-interactively and writes the result to stdout.

If you want to run apidog run directly in CI without Codex, Apidog CLI in GitHub Actions covers secrets, reporters, and exit-code gating.

Troubleshooting

Codex ignores AGENTS.md

If Codex runs a generic command or no command at all, confirm:

  • the file is named exactly AGENTS.md
  • it is at your Git root or a parent of your current directory
  • you restarted Codex after creating or editing it

A filename typo means Codex never reads it.

Codex adds an access token

If Codex tries to add:

--access-token
Enter fullscreen mode Exit fullscreen mode

it is guessing from examples.

If your machine is already authenticated with:

apidog login
Enter fullscreen mode Exit fullscreen mode

do not put a real token in AGENTS.md. Reinforce the instruction:

Do not pass --access-token. Use the existing authenticated Apidog CLI session.
Enter fullscreen mode Exit fullscreen mode

Codex invents a flag

If you see an “unknown option” error, ask Codex to inspect the installed CLI version:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Then use the exact flag names shown by your installed version.

Codex reports success on a failed run

This is the most expensive failure mode.

Require Codex to report the exit code. If the prose summary and exit code disagree, the exit code wins.

Final setup

Install apidog-cli once by following the install guide. Add your real apidog run command to the repo’s AGENTS.md. Then let Codex run your API scenario as part of its normal edit-test-fix loop.

A GUI-only test runs when a human clicks. A CLI-backed scenario can run whenever Codex changes API behavior.

Keep building scenarios visually in Apidog, then drop the generated apidog run command into AGENTS.md. To get started, download Apidog, create one scenario, and let Codex pick it up on the next change.

Top comments (0)