How to Use the Apidog CLI in DeepSeek Harness

DeepSeek Harness is a loop. The agent reads your workspace, edits files, runs commands through its bash tool, and decides what to do next based on the output. So why aren’t your API tests in that loop? They sit in Apidog behind a GUI and run when someone remembers to click. The 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 DeepSeek Harness knows it exists, the 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.

There is also a token argument for doing this. An agent that confirms your API still works by re-reading handler code and reasoning about response shapes burns context on every pass. An agent that runs one command gets ground truth back in a few lines. The CLI compresses “is the API correct?” into an exit code, and the agent spends its context on the fix instead.

This guide covers the harness-specific part the generic install guide skips: which instructions file DeepSeek Harness actually reads, how its bash tool executes apidog run, and how to keep the loop honest. 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, authentication, and the first run. This article assumes apidog --version prints a number and your machine is authenticated.

Which DeepSeek Harness this is about

DeepSeek Harness, dsh on the command line, is the open-source agent harness DeepSeek released on August 13, 2026, alongside V4-Pro on the API. It is MIT licensed, sits at github.com/deepseek-ai/deepseek-harness, and had climbed past 169k stars as of August 20.

Start it with:

npx @deepseek-ai/dsh web

This serves a local web UI at http://127.0.0.1:3080. Select a workspace—the project directory where you launched it—and the agent works inside it: reading and editing files, running commands, and asking before operations that require approval under the active permission policy.

Two details shape the setup below:

1. DeepSeek Harness is a developer preview. Its README warns that compatibility-breaking changes will happen. Treat the file names and config keys here as accurate for late August 2026, and re-check the repo docs if something does not load.
2. Everything in dsh is a plugin built on the Cordis architecture. That makes the key question answerable: which plugin reads project rules, and what files does it load?

For a broader introduction, see what DeepSeek Harness is. For a comparison with the incumbent, see DeepSeek Harness vs Claude Code.

Step 1: put the CLI in AGENTS.md

DeepSeek Harness reads workspace instructions through its @deepseek-ai/dsh-agent-instructions plugin. According to the plugin source and the config catalog, the loader walks upward from the session working directory to the project root, marked by .git.

It loads these files in each directory:

• AGENTS.md
• CLAUDE.md as a fallback
• AGENTS.local.md as a local overlay
• CLAUDE.local.md as a local overlay

Local overlays load after base files. A user-global AGENTS.md in $DSH_HOME, which defaults to ~/.dsh, applies across projects. Files larger than 1 MiB are ignored.

If your repository already has an AGENTS.md for Codex or a CLAUDE.md for Claude Code, DeepSeek Harness can use it without extra setup. Add an Apidog block like this:

## 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. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.

Use the repository-level file for real scenario and environment IDs. If you work across projects, use ~/.dsh/AGENTS.md for a general rule such as:

Always verify API changes with the project's apidog run command.

Keep the project-specific IDs in each repository’s own AGENTS.md.

Step 2: get the command from Apidog

Do not guess scenario or environment IDs.

1. Open the test scenario in Apidog.
2. Go to the CI/CD tab.
3. Copy the generated command.
4. Paste it into your repository’s AGENTS.md.

The generated command looks like this:

apidog run -t 123456 -e 789012 -r cli

The flags are:

• -t: test scenario ID
• -e: environment ID
• -r cli: inline reporter output

The cli reporter is important because it gives the agent output it can read directly. Put the real command from Apidog in AGENTS.md so the agent runs the configured scenario rather than inventing IDs.

Step 3: have the agent run the test

Start a session in the dsh web UI with the correct workspace selected. Because the instruction loader has already included your AGENTS.md, the agent knows the command to run.

After changing API code, ask:

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

The agent executes the scenario through its bash tool. According to the tool catalog, the default bash tool runs every command in a fresh shell.

That means:

• Working directories do not persist between tool calls.
• Environment variables do not persist between calls.
• Shell functions do not persist between calls.
• Commands run from the session workspace unless the tool receives a workdir.

This works well for a self-contained command such as:

apidog run -t 123456 -e 789012 -r cli

Do not rely on the agent running cd some-directory in one command and apidog run ... in the next. If the test must run from a subdirectory, keep the full invocation on one line in your instructions file.

A non-zero command exit is returned with an explicit marker:

[exit code: N]

That preserves the pass/fail signal even if long command output is truncated. Commands can also run under a file sandbox. If the sandbox blocks an operation, dsh reports a policy denial rather than a command failure. A read-only test run should rarely trigger this, but the HTML reporter may need permission to write to ./apidog-reports.

Whether the command requires approval depends on the active permission policy. The web UI asks before operations that require approval under that policy, as described in the user guide. If dsh prompts for apidog run, approve it when the scenario is safe for the target environment.

Step 4: read the report

When a scenario fails, use the CLI output to drive the next edit.

With -r cli, the agent receives an inline breakdown of:

• Requests made by the scenario
• Assertions evaluated
• Failed assertions
• Expected versus actual values

For example, a failure may identify a wrong status code, a missing total field, or an incorrect currency code. That is usually enough for the agent to find the relevant handler and make a targeted fix.

To also create a report you can open in a browser or share with a teammate, add the HTML reporter:

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

The html reporter writes a self-contained file to ./apidog-reports. Keep cli in the reporter list so the agent still receives inline output for its edit-test-fix loop.

The loop, end to end

Suppose the agent is editing a checkout handler.

Without the CLI, the loop may end at: “the code looks right.”

With the command in AGENTS.md, the loop becomes:

1. Edit the handler.
2. Run the scenario:

   apidog run -t 123456 -e 789012 -r cli

1. Read the result.
2. If the command exits with 0, move on.
3. If it returns [exit code: 1], inspect the failed assertion.
4. Patch the handler.
5. Run the scenario again.

The agent can now catch problems such as:

• A 500 response where 200 is expected
• A missing total field
• A wrong currency code

The API contract check becomes part of the same edit-test-fix cycle used for unit tests.

The agent does not need to re-read every route file to reason about whether the API works. The scenario already encodes expected behavior and can be authored visually in Apidog. The agent delegates verification to a deterministic command and uses its context on the fix.

Verify dsh actually ran it

Do not accept a success summary without checking the tool call. Use these three checks.

1. Confirm the command ran

The dsh web UI shows agent tool calls and output in the session. Look for the literal bash call:

apidog run ...

If the agent says it ran tests but no matching tool call appears, 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?

On failure, dsh returns an explicit [exit code: N] marker. If an agent summary says “tests passed” but the command has a non-zero marker, trust the marker.

3. Confirm it used the real scenario

A “scenario not found” error usually means the agent invented or misremembered an ID.

Compare the -t and -e values against:

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

The IDs in the rules file are the source of truth.

Optional: add the Apidog MCP server for spec access

Running scenarios verifies behavior. If you also want the agent to read your API specification while writing code, use MCP.

As of late August 2026, MCP support is not documented in the DeepSeek Harness core README or user guide. A community plugin, hyqhyq3/dsh-mcp-manager, is available through the dsh-plugin GitHub topic. It provides:

• An MCP page in Settings
• Support for remote HTTP and local stdio servers
• Tools registered as mcp__<name>__*
• Per-project server definitions in <workspace>/.dsh/dshmm/mcp.json

You can use it to connect the Apidog MCP server, which exposes API specifications over MCP. This lets the agent inspect an endpoint schema before writing the handler instead of discovering a mismatch only after a scenario fails.

Treat this as an optional layer. Both the host harness and the community plugin can change. The CLI integration remains the load-bearing path because it only needs a shell.

Preview caveats, and where this goes

DeepSeek Harness is moving quickly and explicitly warns about breaking changes. Re-check these details when upgrading:

• Instructions plugin file candidates
• Bash tool sandbox behavior and reporting
• Community MCP plugin configuration

The pattern is portable:

1. Put a verification command in a rules file.
2. Use a CLI that returns a clear exit code.
3. Require the agent to run that command after API changes.

That works in dsh for the same reason it works in Claude Code and other coding harnesses: agents can read command output, but they should not be trusted without it.

So, download Apidog, build one test scenario visually, copy its apidog run command from the CI/CD tab, and add it to your repository’s AGENTS.md. The next time DeepSeek Harness changes API code, it can check its own work before reporting that it is done.

FAQ

Does DeepSeek Harness read AGENTS.md natively?

Yes. The @deepseek-ai/dsh-agent-instructions plugin loads AGENTS.md, with CLAUDE.md as a fallback, from the project root and directories above the session working directory. It also supports AGENTS.local.md and CLAUDE.local.md overlays, plus a user-global AGENTS.md in ~/.dsh.

If you already maintain an AGENTS.md for other agents, dsh can use it unchanged.

Do I need a paid DeepSeek plan to use the Apidog CLI in dsh?

No. The harness is MIT-licensed open source, and you bring your own model. Catalog providers cover Anthropic, OpenAI, Bedrock, Vertex, and Azure. Custom gateways work through settings.yaml, as covered in how to run any model in DeepSeek Harness.

The Apidog CLI is a free npm package. It requires an Apidog test scenario and authentication, not a specific model.

Why does the agent’s second command forget the directory the first one changed to?

This is by design. The default dsh bash tool runs every call in a fresh shell, so cd does not persist between commands.

Pass the tool’s workdir parameter or, more simply, keep the complete apidog run invocation on one line in your rules file.

Can dsh run the scenario without asking me every time?

That depends on the active permission policy. The web UI asks before operations that require approval under that policy. The user guide does not enumerate policy levels, so check Settings in your build to see what your deployment allows.

When dsh prompts, approving an apidog run command against staging is a safe choice for a read-mostly verification step.