Running DSH plugin commands in scripts and CI safely

Putting dsh plugin commands into scripts and CI comes down to three things: use commands that exit when done, judge success by exit code rather than output, and pre-supply answers for anything that would ask for confirmation. dsh plugin --profile <name> add / remove / list and dsh --profile <name> --dump-config are all one-shot commands; the CLI returns non-zero for invalid commands, misused arguments, configuration errors, and startup failures, so set -e in a script catches the vast majority of failures (source).

Which dsh plugin commands belong in scripts, and which will hang

The dividing line is whether they exit when done: one-shot commands fit a pipeline, resident processes do not (source). Run through the common commands by that standard:

There is another form of "hanging": the command is not stuck, it is waiting for confirmation. pnpm stops for an answer in two situations — the purge confirmation before deleting node_modules, and build script authorization for git dependencies. Locally you tap Enter without thinking; in CI you wait until the timeout. Both confirmations must be answered in advance via an argument or a config file, as the non-interactive form below shows.

Judge DSH plugin success by exit code, not by grepping the output

The success contract for dsh plugin commands is the exit code, not the output text: output changes with version and locale, exit codes do not (source). Let failures abort directly:

set -euo pipefail

dsh plugin --profile web add "<package>"
dsh --profile web --dump-config | grep -q "# =="

That second line is the real acceptance check: a successful add only means the dependency was installed, whereas a # == <package> line in --dump-config means the config layer entered the bundle tree (source). Keeping the two steps separate lets the log distinguish "could not install" from "installed but not live" at a glance — the latter usually means the package does not declare dsh.bundle.

When you need branching, use if rather than parsing text:

if dsh plugin --profile web list | grep -q "<package>"; then
  echo "already installed"
else
  dsh plugin --profile web add "<package>"
fi

Do not treat grep "error" as a failure test: the word can appear in pnpm warning text, while the real failure is already expressed by a non-zero exit code.

Idempotent DSH plugin reruns: what to do when it is already installed

"Rerun toward the desired state" beats "rerun the action": read the current state first, then decide whether to act (source). Two practices:

1. Make the state query the script's first step:

dsh plugin --profile web list

Its output comes from the pnpm inside the profile directory and shows package names and versions. Using it as the basis makes the script's logic explicit, instead of depending on the implicit behavior of "what happens if I add again".

2. When you need a fixed version, put the version into the target. The worst thing to write in a script is "latest" — working today and failing tomorrow because upstream published a new release. Pin the target to a specific version or commit so reruns stay stable:

# npm package: with a version
dsh plugin --profile web add "<package>@<version>"

# GitHub source: lock the commit
dsh plugin --profile web add github:owner/repo#<sha>

Install it by hand once locally before writing the script: clicking install for the same package in DSH Plugin Hub verifies that "the plugin itself installs and is actually live", and once confirmed you can move the equivalent command into the script. Skip this and it becomes hard to tell whether the plugin or the script is at fault.

The minimal working form for dsh plugin in CI and containers

Three prerequisites in a container: a recent enough Node version, pnpm on PATH, and a writable $DSH_HOME; once met, one command is enough (source). The minimal snippet:

npm install -g pnpm

export CI=true
export DSH_HOME="${HOME}/.dsh"

dsh plugin --profile web add --config.confirm-modules-purge=false "<package>"
dsh --profile web --dump-config | grep -q "# =="

The points, one by one:

1. CI=true puts pnpm on the non-interactive branch, so anything that would have prompted is handled non-interactively;
2. --config.confirm-modules-purge=false disables the confirmation before deleting node_modules, avoiding a stall while clearing caches;
3. pnpm must be on PATH — with no pnpm in the container image, the command fails in the shape of pnpm failed in profile directory; how to diagnose that is in how to fix "pnpm failed in profile directory";
4. On restricted networks the registry must point at an internal source, or the build stage stalls fetching packages — see how to install dsh on an intranet or offline;
5. Authorize git dependencies in advance: write pnpm's exact printed package key into that profile's pnpm-workspace.yaml:

allowBuilds:
  <package>: true

This step pre-authorizes install-time code execution, so use it only for packages whose source you trust (source).

DSH plugin scripting notes

In one line: pick commands that exit, judge by exit code, pre-answer confirmations, and pin versions. Seven reminders:

1. Resident commands do not go into a pipeline: processes like dsh web hold the terminal and only suit background services;
2. Accept with --dump-config: the add exit code only proves the dependency was installed; the config layer must be confirmed in the bundle tree;
3. Do not parse output text: wording and versions both change, only the exit code is a stable contract;
4. Always pin the version: write <package>@<version> or #<sha> so reruns do not drift with upstream;
5. Supply confirmations in advance: disable purge with an argument and authorize build scripts with allowBuilds, rather than letting CI wait for an Enter key;
6. $DSH_HOME must be writable: in a container the default path may land on a read-only layer, so point it explicitly at a writable volume when needed and keep it consistent across steps;
7. Back up the profile before upgrading: cp -r "$DSH_HOME/profiles/<name>" "$DSH_HOME/profiles/<name>.bak" so a script that breaks something can be restored directory by directory.

Once the commands are composed for non-interactive use, what remains is argument detail; if you want a full command reference sorted by feature or alphabetically, that is a different kind of article — this one only covers "getting it to run unattended".

Sources: dsh CLI README, DeepSeek Harness docs - Packaging and installing a plugin