Profiles vs bundles

The install commands deal with two different objects: bundles, which are packages, and profiles, which are compositions of packages. The difference explains both how the CLI works and what the catalog contains.

A bundle is a package

A bundle is an npm package whose package.json declares a dsh.bundle manifest. That declaration is what makes it a plugin rather than a library: it ships a patch layer (cordis.patch.yml) and the module the layer references, and installing it into a profile activates that layer. Bundles are what authors publish, and they are the only thing this catalog lists.

A profile is a composition

A profile is one runnable composition of bundles: the list plus its order. The CLI manages profiles for you — installing adds a bundle, removing drops it, and the order of the list is the order the layers apply, with later bundles overriding earlier ones. A profile is local, generated state on your machine ($DSH_HOME/profiles/<name>), never published and never listed in the catalog.

A typical workflow

Name a profile in the install command and the first install creates it, seeded with @deepseek-ai/dsh-base as its first bundle. Install a couple of bundles, then confirm the layers applied in order:

dsh plugin --profile demo add <bundle-a>
dsh plugin --profile demo add <bundle-b>
dsh --profile demo --dump-config

The verify output shows the layers in the profile's bundle order, which is the order the profile will apply at boot. Remove a bundle the same way when you are done:

dsh plugin --profile demo remove <bundle-b>

Why the distinction matters

If you remember only one thing: the catalog is a list of bundles. A profile is your local answer to "which bundles do I run together, and in what order" — two machines can have completely different profiles built from the same listings. When a package is missing from the catalog but installs locally, check whether it actually declares dsh.bundle: without it, the package is a library that installs into a profile but adds no layer.

Neither concept replaces the other. You publish a bundle once and reuse it in as many profiles as you like, and every profile is reproducible from the same public bundles. That is the whole model: bundles are the units of distribution, profiles are the units of execution.