Plugin lifecycle: install it, unplug it (Plugin Lifecycle)

For every dsh user, especially those with a pile of plugins to clean up. This

chapter covers the boundary of the official dsh plugin commands, and how

dsh-unplug makes every plugin truly pluggable: list, full uninstall,

disable-without-delete, and one-command repair.

1. What the official CLI can and cannot do

The official dsh plugin has two core concepts:

• bundle — an npm package whose manifest declares dsh.bundle.patch, listed

in the profile's dsh.profile.bundles;

• patch rows — plugin rows under - insert: / - override: in

cordis.patch.yml (profile level and home level).

dsh plugin --profile <name> add <pkg> writes both the bundles list and the pnpm

dependency; dsh plugin --profile <name> remove <pkg> only touches the bundles

list and dependencies. It leaves behind:

1. plugin rows still present in profile/home cordis.patch.yml;

2. no disable-without-delete (and later re-enable);

3. no post-removal audit (orphan rows, dangling bundles).

That is exactly why plugins feel easy to install but hard to unplug.

2. Install dsh-unplug

dsh plugin add dsh-unplug

Zero runtime dependencies, read-only by default; destructive operations require

explicit confirmation (--yes / --force on the CLI, force: true for the

agent tool).

3. The daily three commands

dsh-unplug                    # no args → friendly menu
dsh-unplug list               # what is installed (bundles + patch rows)
dsh-unplug fix --yes          # one-command repair: dangling bundles + orphan rows

Cleaning up:

dsh-unplug remove <plugin> --yes          # full uninstall (bundle + rows + deps)
dsh-unplug remove --dry-run <plugin>      # preview only, nothing is executed
dsh-unplug disable <plugin>               # disable without deleting; enable anytime
dsh-unplug enable <plugin>

Forgot the name? Just run dsh-unplug remove and it lists installed plugins with

copy-paste-ready commands.

4. What it actually changes

Layer	remove	disable
dsh.profile.bundles	removed from list	moved to disabledBundles
dependencies	pnpm remove	kept
profile cordis.patch.yml	row deleted	row gets disabled: true
home cordis.patch.yml	same	same
leftovers	auto re-audits after	—

reconcile / fix do the reverse: drop unresolvable entries from the bundles

list and strip rows that reference packages which no longer exist.

5. Audit & troubleshooting

dsh-unplug audit --json       # machine-readable: orphan rows / dangling bundles / missing patches
dsh-unplug list --all         # scan every profile at once

Best practice: after an upgrade or when dsh fails to boot post-removal, run

dsh-unplug audit first, then compare with dsh --profile <name> --dump-config.

6. Notes

• remove is destructive: it removes dependencies and edits patch files. Use

--dry-run before --yes;

• rows contributed by official bundles (e.g. the tool rows inside

@deepseek-ai/dsh-base) are not orphans — audit only reports orphans at

profile/home layer;

• repository: github.com/zoahdev/dsh-unplug (npm: dsh-unplug).