The dsh CLI cheat sheet
Every DeepSeek Harness command worth memorizing — install, launch, modes, plugins, config and version pinning — in printable tables.
Last updated: 2026-10-01
dsh is the command line entry point for DeepSeek Harness: one binary that boots every surface — the Web UI, terminal sessions, one-shot headless runs, and the automation profiles. It is also the fastest path to install, update and repair the whole harness.
This page is the quick reference: verified commands only, taken from the official apps/cli README, the root README and the npm package, and cross-checked against our step-by-step guides. Print it, keep it next to your terminal, and follow the links when you need the full walkthrough.
TL;DR
- ▸Install once with npm install -g @deepseek-ai/dsh (Node.js 20+), or skip the install with npx @deepseek-ai/dsh web.
- ▸dsh web boots the Web UI at 127.0.0.1:3080; dsh --profile <name> boots any other profile; dsh --profile headless runs one task and exits.
- ▸Plugins are per-profile: whatever --profile you install with (dsh plugin --profile web add) is the profile you must launch with.
- ▸Update with @latest, roll back with an exact version (@0.2.0-rc.2), and check dsh --version before any diagnosis.
Install and first launch
Four steps from nothing to a running harness. The npm route is the documented one; the source route exists for development.
- 1
Check the runtime
dsh runs on Node.js 20 or newer (Node 22 LTS recommended). In any terminal, node -v should print v20.0.0 or higher — that single check prevents the most common plugin-failed-to-register tickets.
$node -v - 2
Install the CLI globally
One global install puts the dsh command on your PATH; verify with dsh --version before moving on. On the macOS and Windows desktop app (0.2.0-rc.2 or newer), the Manage dsh command menu-bar item can install the command for you — no separate Node.js or pnpm needed.
$npm install -g @deepseek-ai/dsh$dsh --version - 3
Launch, with or without installing
npx @deepseek-ai/dsh web runs the current version without any global install — the fastest first look. dsh web does the same from a global install: it boots the Web profile, opens your browser, and the command prints its URL (127.0.0.1:3080 by default; --no-open skips the browser, --port changes it; over SSH it only prints the host URL). First model connection happens in Settings → Models.
$npx @deepseek-ai/dsh web$dsh web - 4
Alternative: run from source
For development: clone the repository, install and build once, then pnpm dsh web uses the built artifacts without rebuilding. The same launcher forwards every argument — pnpm dsh --profile headless takes the task in quotes and needs DEEPSEEK_API_KEY in the environment or a repo-root .env.
$git clone https://github.com/deepseek-ai/deepseek-harness$pnpm install$pnpm run build$pnpm dsh web
Profiles, registry mirrors and the vetting checklist for third-party plugins are in the install guide: Installing plugins you can trust
Modes: what each entry point boots
dsh has no separate desktop, server or client binaries — one launcher, different profiles. The shipped profiles below initialize themselves from templates on first use.
| Mode | Command | What it gives you |
|---|---|---|
| Web UI | dsh web | The dashboard in your browser at 127.0.0.1:3080 — workspaces, the plugin market, settings. The everyday visual surface. |
| Headless | dsh --profile headless "task" | One fresh persisted session per invocation: runs the task, prints the final answer, exits. Built for scripts and CI. |
| ACP | dsh --profile acp | The official automation-only Agent Client Protocol server over JSON-RPC stdio — for editors and automation clients; intentionally omits plans, titles and terminal views. |
| SDK | dsh --profile sdk | Serves SDK clients over JSON-RPC stdio until shutdown or disconnect — programmatic integrations. |
| SDK Minimal | dsh --profile sdk-minimal | Serves SDK clients against the standalone minimal agent tree — the lightweight embedding. |
| TUI | dsh --profile tui | Terminal-native sessions; the --resume <id> flag belongs to this terminal app. |
| Desktop | — | Reserved for the Electron desktop app — the CLI refuses to boot it, dump its config or manage its plugins. |
Mode is the surface; the agent preset decides what a session can do — Standard, PTC, Minimal and Creator ship built in, and the difference is the toolbox: The four modes: Standard, PTC, Minimal, Creator
The command cheat tables
Grouped for printing: plugins, sessions and profiles, config inspection, diagnostics — then version management below. Commands are verbatim; the flag you install with must match the flag you launch with.
Plugins — install and manage per profile
| Command | What it does |
|---|---|
| dsh plugin --profile web list | Print a profile's plugin entries and its directory on disk — verify before anything else. |
| dsh plugin --profile web add <package> | Install a plugin from the npm registry into the web profile (swap the profile name to match yours). |
| dsh plugin --profile web add github:owner/repo#tag | Install a GitHub-only plugin, pinned to a branch or tag with the #ref. |
| dsh plugin --profile web add ./path/to/plugin | Install a plugin from a local folder — the local-development route. |
| dsh plugin --profile web update | Update the plugins of a profile. |
| dsh plugin --profile web remove <package> | Remove a plugin from a profile. |
Sessions and profiles
| Command | What it does |
|---|---|
| dsh web | Boot the Web profile — the same as dsh --profile web; the command prints its URL. |
| dsh --profile <name> | Boot the named profile from $DSH_HOME/profiles/<name> (web, headless, acp, sdk, sdk-minimal and tui auto-initialize from shipped templates on first use). |
| dsh --profile headless "one-off task" | Headless one-shot: one fresh persisted session, print the final answer, exit. |
| dsh --profile tui --resume <id> | Resume a persisted session in the terminal app. |
| dsh --profile <name> --from-default-profile web | Create a new custom profile from a shipped template, then boot it. |
Config — inspect before you edit
| Command | What it does |
|---|---|
| dsh --dump-default-config | Print the composed default tree without booting it — what stock dsh would assemble. |
| dsh --dump-config | Print the composed tree with your profile and patch overlays applied — still without booting. |
| dsh --dump-config-schema | Print the JSON Schema for plugin entries and patches instead of config values. |
| dsh --patch <file> | Overlay an extra patch file on top of the composed tree for this launch. |
| cat ~/.dsh/profiles/<name>/cordis.patch.yml | Read a profile's patch file by hand — the workspace-level .dsh/cordis.patch.yml overrides it when present. |
Layering order: bundle patches → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch overlays. Every config change starts with the question of which layer you are editing — Profiles, patches & presets
Diagnostics
| Command | What it does |
|---|---|
| dsh --version | Show the runtime version (used for peer-range checks). Run it before any diagnosis. |
| dsh --help | The launcher's own help; app-level flags differ per profile (try dsh --profile web --help). |
| node -v | Confirm Node.js 20+ — the most common cause of plugins failing to register. |
| npm prefix -g | Print the npm global prefix — the dsh binary lives in its bin directory; compare against your PATH when the shell says command not found. |
When a command here fails, the symptom → cause → fix encyclopedia covers it step by step: Troubleshooting & error encyclopedia
Version management
Update and roll back are the same command — the only difference is the tag. Check npm's dist-tags or the release notes before riding a pre-release channel.
| Command | What it does |
|---|---|
| npm install -g @deepseek-ai/dsh@latest | Update the CLI to the newest npm latest — 0.2.0-rc.2 as of 2026-10-01. |
| npm install -g @deepseek-ai/dsh@<exact-version> | Pin (or roll back to) an exact version — never @latest when reproducing or recovering. |
| dsh plugin --profile web update | Update the plugins of a profile. |
| dsh plugin --profile web add github:owner/repo#v1.2.3 | Pin a plugin to a tag instead of a moving branch. |
Back up ~/.dsh/profiles/<name>/cordis.patch.yml before upgrading — the 0.2.0-rc upgrade wave filled the discussions with cleared workspaces and plugins failing in bulk.
The full update and rollback walkthrough, including the Web UI market route: Update DSH & plugins
Platform one-liners
Copy-paste blocks per platform. All four end in the same place: the Web UI at 127.0.0.1:3080.
macOS
In Terminal, run without installing — npm asks once, answer y:
Windows
In PowerShell (no WSL required): install once, then launch —
Linux
Check the runtime, then run without a global install:
WSL2
Inside WSL2, use the Linux commands as-is; dsh also runs natively on Windows, so pick one home and stay in it — mixing homes splits your ~/.dsh.
dsh CLI FAQ
The questions that come up once the cheat sheet is open.
Is dsh the same thing as DeepSeek Harness?
dsh is the harness's command line entry point — the published npm package @deepseek-ai/dsh. The desktop app and the Web UI are surfaces over the same tree: dsh web boots the Web profile from the same install. Since 0.2.0-rc.2 the macOS/Windows desktop app also ships a Manage dsh command menu item that installs and manages that same CLI, plugins included, without a separate Node.js or pnpm installation.
Should I use npx @deepseek-ai/dsh web or install dsh first?
npx is the zero-install route — it fetches the package and runs the Web UI once, which makes it the fastest first look and a stopgap when your global install is broken. For daily use, install globally (npm install -g @deepseek-ai/dsh): dsh web then starts instantly, dsh --version tells you what you are actually running, and dsh plugin manages your plugins. Verify either route with dsh --version.
I installed a plugin but dsh starts without it. Where did it go?
Almost always a profile mismatch. dsh plugin --profile web add <package> writes the entry into the web profile — if you then launch a bare dsh (the default profile), that tree does not contain the plugin. Run dsh plugin --profile web list to confirm the entry and its directory, then start with dsh --profile web. The same rule applies to every flag: install and launch must match.
Where do profiles live, and how do I create one?
Profiles live under $DSH_HOME/profiles/<name> — inside the harness home, ~/.dsh by default (DSH_HOME moves it). The shipped profiles (web, headless, acp, sdk, sdk-minimal, tui) initialize themselves from templates on first use. For a custom profile, dsh --profile <name> --from-default-profile web copies a shipped template and boots it. Inspect any composition without booting via dsh --dump-config.
What is the desktop profile — and why does dsh reject it?
The name desktop is reserved for the Electron desktop app. The CLI refuses to boot it, dump its config or manage its plugins, so dsh --profile desktop exits with an error by design. Use the desktop app itself for that surface; use dsh web for the browser route.
How do I update dsh, and how do I roll back?
Update: npm install -g @deepseek-ai/dsh@latest (npm latest is 0.2.0-rc.2 as of 2026-10-01), then dsh --version to confirm. Roll back: install an exact version instead — npm install -g @deepseek-ai/dsh@0.1.5-rc.2 — never @latest. Back up ~/.dsh/profiles/<name>/cordis.patch.yml first, and pin individual plugins with dsh plugin add github:owner/repo#v1.2.3.
Related guides
The long-form walkthroughs behind each cheat table.
DeepSeek Harness: the 10-step tour
From git clone to headless mode — install, providers, presets, creator-mode plugins, sandboxing and receipts, in one guided walkthrough.
Read the guideInstalling plugins you can trust
How plugin installation actually works in dsh, plus a checklist for vetting third-party code.
Read the guideThe four modes: Standard, PTC, Minimal, Creator
What each agent preset includes, when it wins, and how to build a preset of your own in Creator mode.
Read the guideProfiles, patches & presets
How a dsh process is assembled from stacked config layers — and how to make it yours.
Read the guideUpdate DSH & plugins
Verified update commands: check your version, upgrade the dsh CLI, refresh plugins from the terminal or the Web UI market, and roll back safely.
Read the guideTroubleshooting & error encyclopedia
Symptom → cause → fix: install failures, pnpm workspace allowlist errors, cordis.patch.yml conflicts, bundle format errors, and profiles that won't apply.
Read the guide