dsh CLI: DeepSeek Harness install, commands, DSH plugins

dsh cli means the DeepSeek Harness command-line tool dsh — the sole officially supported Node application launcher, which loads a profile and hands the remaining arguments to it; the Web UI, headless jobs and the SDK are all different profiles it boots.

DeepSeek Harness CLI overview

This guide covers three things about "dsh CLI": what it is and how it relates to the Web and desktop builds, how to install it, and the three command families you use day to day plus their exit codes. Conclusion first: it is not a standalone product but the common entry to every form — every dsh command you type is essentially "pick a profile and boot it". For command details, use the dsh command cheatsheet; this piece focuses on the concepts and the install.

What dsh CLI is: the DeepSeek Harness launcher and its relation to Web and desktop

dsh is the DeepSeek Harness command-line launcher; it does exactly one thing: load the selected profile and hand the remaining arguments to the booted app to parse (source). To get it right, four points:

• It is the sole entry — the vendor states the dsh command is the only supported Node application launcher; the SDK and ACP are profiles, not separate public binaries.
• Syntax and loading are separate — the command grammar lives in src/args.ts, while src/bin.ts only dynamically loads the selected runner, so the "hand off what I don't recognize" boundary is very stable.
• It is not "another interface" — the Web UI is the web profile booted by dsh web rendered in a browser, a headless job is the headless profile, and SDK/ACP are their own profiles; different interfaces over one shared capability set.
• Relation to the desktop build — the desktop and Web UI give you a graphical, browsing interface, while the CLI gives you the same capabilities from a command line, so you switch between them by scenario. For that trade-off, see DeepSeek Harness Web UI vs desktop.

In one line: the CLI is a launcher, not an interface; what you change is what it boots, not the CLI itself.

dsh web and dsh --profile web are the same load

dsh web is just a hardcoded alias for dsh --profile web: both load the web profile and hand the remaining arguments to it (source). Likewise, dsh <name> abbreviates dsh --profile <name> and boots the same-named profile under $DSH_HOME/profiles/<name>. The directory you launch dsh from becomes its default workspace root, while the profile always lives under $DSH_HOME/profiles/<name>. So don't treat dsh web as another product — it and dsh --profile headless "job" take the same load path, differing only in which profile they pick. The launcher parses only its own flags (--profile, --patch, --help and the like); after the first token it doesn't recognize, the rest goes to the booted app verbatim (source).

How to install dsh CLI: npm global install vs npx

There are two ways to install the CLI: npm install -g @deepseek-ai/dsh for a global install and then call dsh directly, or skip the install and run npx @deepseek-ai/dsh to pull it on the fly (source). Go in order:

1. Confirm Node and npm are present — run node -v and npm -v. Expected: both print a version number.
2. Install globally — run npm install -g @deepseek-ai/dsh. Expected: the install succeeds and dsh --version prints the launcher version.
3. Boot the Web UI — run dsh web. Expected: the terminal prints the address and the service runs at http://127.0.0.1:3080.
4. Or run without installing via npx — run npx @deepseek-ai/dsh web. Expected: the same result as the local install, only pulling the latest version each time.
5. Set the key and workspace — in the Web UI settings, enter the API key and pick a workspace. Expected: you can send your first task.
6. Add plugins — when you need to extend capabilities, add them from the plugin market (see the link below). Expected: the plugin's capabilities appear in the interface.

# after a global install, call dsh directly
npm install -g @deepseek-ai/dsh
dsh web

# without installing, run it on the fly with npx
npx @deepseek-ai/dsh web

# confirm the version
dsh --version

The two differ only in whether a package is pulled each time: a global install for long-term daily use, npx for an occasional try-out or a CI run, both reading the same $DSH_HOME data — see the older npx @deepseek-ai/dsh web flags vs global install for the full install, flags and cache comparison.

Common dsh CLI commands: dsh, dsh web, dsh plugin

Three families cover daily use: dsh web boots the Web UI, dsh --profile <name> boots any profile (headless runs a one-shot job), and dsh plugin --profile <name> <pnpm args> manages plugins (source). Quick reference:

A few boundaries you must know (source):

1. Argument ownership — the launcher parses only its own arguments; after the first token it doesn't recognize, everything goes to the app as-is. So in dsh --profile web --port 8080, --port belongs to the web app.
2. dsh web's address is fixed — default http://127.0.0.1:3080, the port changes with --port, but the CLI does not support --host 0.0.0.0.
3. Initialize the profile before installing plugins — run dsh web once before the first add so the web profile exists.
4. One-click plugin management is easier — once the community market plugin is installed, browsing, one-click install, update and uninstall all happen in the GUI.

Argument ownership and common exit codes

A launcher exit code expresses one thing: whether the command and config were accepted — dsh --help exits 0, while rejected arguments or an unknown command exit nonzero (source). The cases you hit most:

1. Usage errors exit nonzero — an unknown subcommand, an option from another mode, or a repeated --profile is rejected before boot and exits nonzero, never booting with the wrong config.
2. --help exits 0 — dsh --help prints the launcher's own help and dsh web --help prints the web app's help; neither actually boots the service.
3. headless exits by task outcome — dsh --profile headless "job" exits 0 when the job completes and 1 otherwise, so it is safe to gate a script on it.
4. Boot failure exits 1 and writes a log — when a required plugin fails to activate, the process prints diagnostics and exits with code 1, and writes a startup-<timestamp>-<uuid>.log under $DSH_HOME/logs/ (default ~/.dsh/logs/).
5. A missing profile fails loudly — a missing profile does not fail silently; it hints to create it with dsh plugin --profile <name> add <package> first.

To master every command's arguments and exit codes, go straight to the dsh command cheatsheet. After a global dsh install, if you would rather manage DeepSeek plugins visually, add DSH Plugin Hub and you can install, update and uninstall from Settings → Plugin market in the Web UI.

Notes and limits for the DeepSeek Harness CLI

1. The launcher parses only its own arguments — everything after the first unrecognized token goes to the app, so an argument in the wrong place is treated as an app argument.
2. Profiles don't interfere — DSH plugins and config are isolated per profile, so web and headless each install their own, and switching profiles swaps the whole plugin set.
3. Web listens only on the local machine by default — it binds 127.0.0.1:3080 and deliberately does not support --host 0.0.0.0; restrict source hosts with --trusted-host.
4. npx pulls the latest every time — no install is convenient, but you don't control the version; pin it with @version or use a global install.
5. Preview changes things — DeepSeek Harness is in developer preview and the vendor states breaking changes are coming (source), so treat the commands and interface as version-specific.

Rather than memorizing the dsh plugin add, remove and update family and checking profile dependencies yourself, add DSH Plugin Hub once dsh is globally installed: the CLI handles launching while the UI handles plugins.

Source: dsh CLI README, @deepseek-ai/dsh on npm, dsh-plugin.org plugin market