DeepSeek Harness CLI: Every dsh Command, Flag, and Footgun in One Place

Foreword

After DeepSeek Harness was open-sourced, many people installed it immediately.

After installation, they discovered a problem—there are so many commands, and they're hard to remember.

dsh web can run, but what does --profile headless do?

When should --patch be used?

What is the difference between --dump-config and --dump-default-config?

How do you install plugins?

What are the rules for parameter order?

I was confused by these questions at first too.

After spending an evening going through the official documentation and community resources, I finally figured out the entire command system.

In this article, I will organize all the dsh commands from start to finish into a complete quick-reference manual.

I hope it helps you.

For more AI project practices, visit: susan.net.cn/project

1. What exactly is dsh?

Before we talk about specific commands, let's take 2 minutes to clarify one thing: what exactly is dsh?

dsh is the command-line entry point for DeepSeek Harness.

Its core function is to start a profile—a profile is a runtime configuration formed by stacking multiple plugin combination packages in sequence.

Simply put: you tell dsh which profile to use, and dsh loads the corresponding plugin combination and runs it as an Agent instance.

Two profiles are built-in:

• web: Starts the Web UI
• headless: One-shot task mode, runs, prints the result, and exits

Both profiles are automatically initialized from the included templates on first use.

Other profiles must be created manually using the dsh plugin command.

2. Startup Commands

2.1 Method 1: One-click start with npx (preferred for first try)

This is the fastest way, suitable for first-time experience and when you don't want to install a global package:

npx -y @deepseek-ai/dsh web

After execution, the browser will automatically open the local interface at the default address http://127.0.0.1:3080. The configuration directory is automatically initialized on first use.

Prerequisite: Requires Node.js ≥ 22.

2.2 Method 2: Global installation (for daily use)

If you plan to use it long-term, global installation is recommended:

npm install -g @deepseek-ai/dsh
dsh web

After installation, simply type dsh web to start, without needing to type npx every time.

Difference between npx and dsh: npx @deepseek-ai/dsh is for initial installation/temporary invocation; after installation, you can use the dsh command directly. All subsequent parameters are identical.

2.3 Method 3: Run from source (suitable for secondary development)

If you want to modify the source code or develop plugins:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

After building, use pnpm dsh instead of the dsh command; parameter usage is identical.

3. Profile Startup Commands

This is the core command pattern of dsh:

dsh --profile <name>

Starts the specified profile located at $DSH_HOME/profiles/<name>.

Built-in profiles:

# Start Web UI (most common)
dsh web                    # Alias for --profile web

# Start Web UI (full syntax)
dsh --profile web

# One-shot task mode
dsh --profile headless "task description"

Custom profiles:

# Start a custom profile named my-agent
dsh --profile my-agent

Note: Profiles other than web and headless must be created first using the dsh plugin command before they can be used.

4. One-shot Task Commands (headless mode)

Don't want to open the interface, just run a task and get the result—this is the core value of headless mode:

dsh --profile headless "your task description"

Practical examples:

# Have the Agent summarize the current repository
dsh --profile headless "Summarize this repository and identify its main packages."

# Run tests and summarize results
dsh --profile headless "Run the tests in the current directory and summarize the results"

# Verify the CLI pipeline is working
dsh --profile headless "Say hello in one line."

After running, it prints the Agent's final answer and exits, suitable for scripting, CI/CD pipelines, and batch processing scenarios.

Meaning of exit codes:

• 0: Headless task completed normally (final round ended)
• Non-zero: Configuration error, startup failure, or task failure

When writing scripts, you can directly use the exit code to determine success or failure.

5. Plugin Management Commands

Harness's motto is "Everything is a plugin," so plugin management is naturally a frequent operation:

dsh plugin --profile <name> <pnpm arguments>

This command forwards pnpm operations to the specified profile directory, used to install and remove plugins for the profile.

Installing plugins:

# Install a community plugin for the web profile
dsh plugin --profile web add dsh-some-plugin

# Install a specific version of a plugin
dsh plugin --profile web add @rvaim/dsh-compat@latest

# Install a terminal plugin for the tui profile
dsh plugin --profile tui add @wxgmjfhy/dsh-tui

# Install a plugin for the headless profile
dsh plugin --profile headless add @useorgx/[email protected]

Removing plugins:

dsh plugin --profile web remove dsh-compat
dsh plugin --profile tui remove @wxgmjfhy/dsh-tui

Note: After plugin changes, you usually need to restart Harness for them to take effect. In the Web UI, you can also manage plugins visually via "Settings → Plugins."

6. Viewing Help and Configuration

6.1 Viewing Help

# View the launcher's own help (parameters for the profile launcher)
dsh --help

# View the Web application's own parameters (not the launcher's)
dsh --profile web --help

# View the headless application's parameters
dsh --profile headless --help

Key difference: Bare --help shows the launcher's help; adding --profile shows the help for that application's parameters.

6.2 Viewing Configuration (useful for troubleshooting)

# View the built-in default configuration (without any patches applied)
dsh --dump-default-config

# View the final configuration after all layers are merged
dsh --dump-config

These two commands inspect the combined configuration tree without starting, very useful for troubleshooting configuration issues.

6.3 Temporarily Overriding Configuration

# Start with a one-time overlay (does not modify files)
dsh --patch <file path> --profile web

--patch replaces the entire config value of the target line, rather than deep-merging the keys within it.

7. The Most Important Rule: Parameter Order

This is the easiest pitfall with dsh commands. The launcher only parses its own flags; starting from the first unrecognized token, everything after belongs to the application parameters.

# ✅ Correct: Launcher parameters first, application parameters after
dsh --profile web --port 8080        # --port is a parameter of the web application
dsh --profile tui --resume <id>      # --resume is a parameter of the terminal application
dsh --profile headless "run tests"   # The task text is an application parameter

# ❌ Incorrect: Application parameters placed before the launcher
dsh --port 8080 --profile web        # Launcher cannot see --profile

# Difference in viewing help
dsh --profile web --help             # View the web application's own parameters
dsh --help                           # View the launcher's parameters

Mnemonic: Launcher parameters first, application parameters last.

8. Python SDK Invocation

In addition to CLI commands, Harness also provides a Python SDK:

# Install the Python library
pip install deepseek-harness

# Install the CLI tool
pip install deepseek-harness-cli

# MCP server (stdio transport)
npx -y @deepseek-harness/mcp

For a complete example of calling Harness in Python code, refer to the official Python SDK documentation.

9. Complete Command Quick Reference

Command	Function
npx @deepseek-ai/dsh web	One-click start Web UI
dsh web	Start Web UI (after global install)
dsh --profile <name>	Start specified profile
dsh --profile headless "task"	One-shot task, exits after completion
dsh plugin --profile <name> <pnpm args>	Manage profile plugins
dsh --help	Launcher's own help
dsh --dump-default-config	Print built-in default configuration
dsh --dump-config	Print final merged configuration
dsh --patch <file>	Start with a one-time overlay
pnpm dsh web	Start from source (after build)

10. Pros and Cons

Pros

1. Concise commands, quick to learn There are only about a dozen core commands, with no more than 5 used daily. dsh web gets you running with a single command.

2. Dual modes cover all scenarios Web UI is suitable for daily development, headless mode is suitable for scripting and CI/CD.

3. Standardized plugin management A single dsh plugin command handles all plugin operations, uniformly managed through pnpm.

4. Auditable configuration --dump-config and --dump-default-config make configuration issues clear at a glance.

5. Clear parameter rules Once you remember the "launcher first, application last" rule, you basically won't make mistakes.

Cons

1. Strict parameter order restrictions Launcher flags must be written at the very front, otherwise they will be misinterpreted as application parameters.

2. Currently still a developer preview dsh is currently at 0.1.0-rc.6 (pre-release stage); please evaluate carefully for production environments.

3. Non-built-in profiles require manual creation Profiles other than web and headless must be created first via dsh plugin.

4. Depends on Node.js environment Requires Node.js ≥ 22 to run.

11. Common Questions Quick Reference

Q: What is the difference between npx and dsh commands? A: npx @deepseek-ai/dsh is for initial installation/temporary invocation; after installation, you can use the dsh command directly.

All subsequent parameters are identical.

Q: Prompt says dsh command not found? A: Confirm whether it is installed, or use the npx @deepseek-ai/dsh prefix instead.

Q: Browser didn't open automatically after startup? A: Manually visit http://127.0.0.1:3080 and confirm the port is not occupied.

Q: --help doesn't show the command I want? A: After adding --profile <name>, --help shows that application's parameters; bare --help is for the launcher.

Q: Headless task is stuck? A: It waits for the Agent to complete all work before exiting; long tasks are normal.

Q: Want to temporarily change configuration without affecting files? A: Use the --patch one-time overlay.

For more AI project practices, visit: susan.net.cn/project

12. Final Words

Back to the original question: How exactly do you use all the commands of DeepSeek Harness?

I've organized the dsh command system into a table:

• Startup: dsh web (Web UI) and dsh --profile headless "task" (one-shot task)
• Configuration: dsh --dump-config and dsh --dump-default-config
• Plugins: dsh plugin --profile <name> <pnpm args>
• Help: dsh --help
• Rule: Launcher parameters first, application parameters last

This command system is very concise—daily use npx @deepseek-ai/dsh web to start the Web UI, batch processing with dsh --profile headless "task", troubleshooting with dsh --dump-config, and managing plugins with dsh plugin.

Remember the rule "launcher parameters first, application parameters last," and you'll basically be able to use it smoothly.