DeepSeek Harness CLI Commands: The Complete dsh Reference

The dsh CLI (npm package @deepseek-ai/dsh) is a launcher that starts apps under named profiles. Everything hangs off a small command surface^[1].

The fastest way to start is npx @deepseek-ai/dsh web, which downloads the package and starts the Web UI at http://127.0.0.1:3080^[1][2].

# One-line launch (requires Node.js)
npx @deepseek-ai/dsh web

# Change the port (app parameters come after launcher flags)
dsh --profile web --port 8080

A profile is a directory under $DSH_HOME/profiles/<name> containing a package.json (with the dsh.profile manifest listing ordered bundles) and a cordis.patch.yml user layer^[1].

The web and headless profiles auto-initialize on first use; other profiles are created through dsh plugin. Each profile is a self-contained agent configuration — different models, different plugin sets, different filesystem roots.

Profiles are cheap: create one per experiment or per client project. If a profile goes sideways, you can inspect its merged config with dsh --dump-config before touching anything, or delete the profile directory to start clean.

Using one profile per project is the community-recommended pattern, because the launch directory becomes the profile's filesystem workspace^[1].

• Profile dir: $DSH_HOME/profiles/<name>
• Config layers merge: bundle patches → profile patch → global patch → --patch
• web/headless auto-initialize; custom profiles via dsh plugin

Headless runs a complete session in one invocation and prints the final answer — designed for scripts, CI, and editor delegation^[1].

Because exit codes are meaningful, headless jobs chain cleanly into CI pipelines and pre-commit hooks. Combine with Cursor's headless channel for IDE-integrated one-shots.

One gotcha: headless uses its own profile, so plugins you installed for the web profile are not automatically present. Run dsh plugin --profile headless add <package> for anything the job needs.

# Run a one-shot agent task
dsh --profile headless "Refactor src/utils.ts and run the tests"

# Non-zero exit = command, config, or startup failure (scriptable)
dsh --profile headless "..." || echo "job failed"

dsh plugin forwards its arguments to pnpm, so any pnpm add/remove pattern works against the profile^[1].

# Add a plugin to the web profile
dsh plugin --profile web add <package-name>

# Add the community plugin market, then browse it
dsh plugin --profile web add dshmarket

# Chat-based plugin finder
dsh plugin --profile web add dsh-find-plugin

# Manage a headless profile's plugins
dsh plugin --profile headless add <package-name>

Before launching a complex stack, inspect what the merged configuration actually contains^[1].

If the merged tree surprises you, the layers to check are: each bundle's patch (in bundle order), the profile cordis.patch.yml, $DSH_HOME/cordis.patch.yml, and any --patch override^[1].

Errors during launch? The troubleshooting guide walks the official error table.

• --dump-default-config: baseline defaults, no launch
• --dump-config: merged result, no launch
• App parameters (like --port) must follow launcher flags

# Print the default config tree
dsh --dump-default-config

# Print the merged tree (bundles + patches + overrides)
dsh --dump-config

# Launcher help
dsh --help