dsh-hub-cliDeepSeek Harness plugin

---

bash
npm install --global @dsh-plugin-hub/cli

# Apply a teammate's Profile to your local "web" harness
dsh-hub profile apply dsh-web-workspace --version 0.1.0 --profile web

That one command installs the exact plugin versions, in the exact order, with the exact patch the author published. Not "whatever is latest today." What they had.

Why shareable Profiles

A DeepSeek Harness (DSH) setup is more than a list of plugins. It is a specific runtime version, a set of plugins at specific versions, the order they load in, a cordis.patch.yml that wires them together, and a handful of environment variables that hold your keys.

Getting that onto a colleague's machine usually means a wiki page, a Slack thread, and an afternoon of "works on my machine."

DSH Hub turns that setup into a first-class, versioned artifact.

mermaid
1flowchart LR
2    subgraph author["Author's machine"]
3        A["~/.dsh/profiles/web<br/>plugins · order · patch · runtime"]
4    end
5    subgraph hub["DSH Plugin Hub"]
6        R["Profile Release<br/><b>dsh-web-workspace@0.1.0</b><br/>sha256 content hash"]
7    end
8    subgraph team["Anyone else"]
9        T1["Teammate"]
10        T2["CI runner"]
11        T3["AI agent"]
12    end
13
14    A -- "dsh-hub profile share" --> R
15    R -- "dsh-hub profile apply" --> T1
16    R -- "dsh-hub profile apply" --> T2
17    R -- "dsh-hub profile apply" --> T3

Without DSH Hub	With a shared Profile
"Install these six plugins"	One slug and one version
Versions drift within days	Every version, source, and integrity hash is locked
Load order lives in someone's head	Order is part of the Release and validated on apply
Secrets get pasted into docs	Only ${ENV_VAR} references are published; values stay local
Upgrades are a fresh install	profile diff shows exactly what changes before you upgrade
Broke it? Start over	profile rollback restores the previous complete revision

What's inside a Profile Release

A Release is a small, content-addressed document. The CLI verifies its hash before doing anything with it.

mermaid
1flowchart TB
2    R["<b>Profile Release</b><br/>dsh-web-workspace @ 0.1.0<br/><code>contentHash: sha256:…</code>"]
3    RT["<b>Runtime</b><br/>@deepseek-ai/dsh 4.2.1"]
4    P["<b>Patch</b><br/>cordis.patch.yml"]
5    I["<b>Inputs</b><br/>OPENAI_API_KEY (secret)<br/>SEARCH_ENDPOINT"]
6    subgraph B["Ordered bundles"]
7        direction TB
8        B1["1 · @deepseek-ai/dsh-base<br/><i>builtin</i>"]
9        B2["2 · dsh-better-sidebar @ 0.15.2<br/>npm · sha512 integrity"]
10        B3["3 · dsh-search @ 2.1.0<br/>npm · sha512 integrity"]
11        B4["4 · acme/dsh-notes # 9f3c…a1<br/>github · pinned commit"]
12        B1 --> B2 --> B3 --> B4
13    end
14    R --> RT
15    R --> B
16    R --> P
17    R --> I

• Runtime pins the exact DSH version the author verified against.
• Bundles are ordered. npm sources carry integrity hashes. GitHub sources must point at a full 40-character commit, never a branch.
• Patch is the author's cordis.patch.yml, published verbatim.
• Inputs declare which environment variables the Profile needs. The CLI refuses to publish a patch that contains a credential-looking value.

Quick start

Requires Node.js 22.13+ and pnpm on your PATH.

bash
npm install --global @dsh-plugin-hub/cli
dsh-hub --help

Apply someone's Profile

bash
1# Find one
2dsh-hub profile search workspace
3
4# See exactly what would change on your machine
5dsh-hub profile diff dsh-web-workspace --version 0.1.0 --profile web
6
7# Apply it (staged, validated, then swapped in atomically)
8dsh-hub profile apply dsh-web-workspace --version 0.1.0 --profile web
9
10# Confirm everything is healthy
11dsh-hub profile doctor --profile web

Share your own

bash
# Preview what would be captured from ~/.dsh/profiles/web
dsh-hub profile share my-stack --version 1.0.0 --profile web --dry-run

# Sign in once, then publish an immutable Release
dsh-hub login
dsh-hub profile share my-stack --version 1.0.0 --profile web

Upgrade and roll back

bash
dsh-hub profile upgrade --version 0.2.0 --profile web --dry-run   # review the diff
dsh-hub profile upgrade --version 0.2.0 --profile web             # apply it
dsh-hub profile history --profile web                             # see saved revisions
dsh-hub profile rollback --profile web                            # restore the previous one

Install a single plugin

bash
dsh-hub search memory
dsh-hub info dsh-context --version 1.2.3
dsh-hub install dsh-context --version 1.2.3 --profile web

How it works

Every mutation is a reviewable plan

Nothing that changes your local harness runs immediately. The CLI first writes a plan: an exact, expiring description of what will happen, plus a fingerprint of the current state. You apply the plan by ID. If the local Profile changed in between, or 30 minutes passed, the plan is rejected and you make a fresh one.

mermaid
1sequenceDiagram
2    autonumber
3    participant U as You / Agent
4    participant CLI as dsh-hub
5    participant Hub as DSH Hub API
6    participant FS as ~/.dsh
7
8    U->>CLI: profile apply dsh-web-workspace --plan --json
9    CLI->>Hub: fetch Release + resolve bundles
10    Hub-->>CLI: Release (hash verified)
11    CLI->>FS: write plan {id, expiresAt, precondition}
12    CLI-->>U: plan JSON (exact versions, sources, inputs)
13    Note over U: Review. Confirm.
14    U->>CLI: operation apply <plan-id>
15    CLI->>FS: check precondition hash + expiry
16    CLI->>FS: stage → install → validate → atomic swap
17    CLI-->>U: operation.completed {revision}

This is what makes the CLI safe to hand to an AI agent. The agent can plan freely, but a human confirms the exact plan ID before anything moves.

Apply is staged, validated, and atomic

mermaid
flowchart LR
    S["Stage into<br/>.hub-web-xxxx/"] --> I["dsh plugin add<br/>each bundle in order"]
    I --> V["Structural check +<br/>dsh --dump-config"]
    V -->|pass| M["Move current web/<br/>to revisions/"]
    M --> W["Rename stage → web/"]
    W --> L["Write lockfile"]
    V -->|fail| X["Delete stage.<br/>Nothing touched."]

The previous Profile directory and its lockfile are kept as a complete revision. Rollback is a rename, not a reinstall.

Packages

mermaid
flowchart LR
    S["<b>schemas</b><br/>zod contracts for<br/>manifests, Releases, API"] --> RG["<b>registry</b><br/>semver resolution,<br/>bundle ordering"]
    RG --> C["<b>cli</b><br/>dsh-hub command,<br/>plans, apply, rollback"]
    C --> P["<b>dsh-plugin</b><br/>agent tools that<br/>call the CLI"]
    C -.->|HTTPS| H["DSH Hub API"]

Package	What it owns
@dsh-plugin-hub/schemas	Runtime-validated Plugin, Profile, and Hub API contracts
@dsh-plugin-hub/registry	Deterministic version resolution and Profile bundle ordering
@dsh-plugin-hub/cli	The dsh-hub command: search, plans, apply, diff, doctor, share, rollback
@dsh-plugin-hub/dsh-plugin	DSH agent tools backed by the same plan/apply pipeline

All four ship in lockstep under one version. See docs/architecture.md for trust boundaries.

Command reference

Command	What it does
dsh-hub search <query>	Search the Plugin catalog
dsh-hub info <package> [--version]	Show a plugin's resolved version, source, compatibility, and security assessment
dsh-hub install <package> [--version] [--profile]	Install one plugin into a local Profile
dsh-hub profile search <query>	Search published Profiles
dsh-hub profile apply <slug> [--version] [--profile]	Apply a Profile Release
dsh-hub profile upgrade [slug] [--version] [--profile]	Upgrade the installed Profile to another Release
dsh-hub profile diff [slug] [--version] [--profile]	Compare local state with a Release
dsh-hub profile doctor [slug] [--profile]	Check directory, lockfile, order, installed versions, required inputs, and drift
dsh-hub profile share <slug> --version <v> [--profile]	Publish the local Profile as an immutable Release
dsh-hub profile capture <slug> [--profile]	Print the captured Profile draft without publishing
dsh-hub profile import <file.dshprofile> [--profile]	Apply a Release from an exported archive
dsh-hub profile history [--profile]	List recoverable local revisions
dsh-hub profile rollback [revision] [--profile]	Restore a previous revision
dsh-hub operation apply <plan-id>	Execute a previously created plan
dsh-hub init [dir] --repository <owner/repo>	Scaffold a new plugin package
dsh-hub validate [dir]	Validate a plugin or Profile package directory
dsh-hub login / logout	Sign in to the Hub with a device code
dsh-hub telemetry state|on|off	Manage anonymous usage reporting

Common flags: --profile <name> (default web), --version <exact|tag|range>, --dry-run, --plan, --json, --no-telemetry, --api <url>.

Use it from an agent

Install the adapter into a Profile and your DSH agent gets eleven tools that map one-to-one onto the CLI:

bash
dsh plugin --profile web add @dsh-plugin-hub/dsh-plugin

Read-only tools (dsh_hub_search, dsh_hub_profile_diff, dsh_hub_profile_doctor, …) run freely. Mutating tools only ever create plans. A single dsh_hub_operation_apply tool executes a plan, and it requires confirmed: true, which the agent may only set after the user approves that exact plan.

The repository also ships a reviewable dsh-hub agent Skill that spells out the confirm-before-apply rules for any agent driving the CLI.

Security and privacy

The CLI installs packages, edits local DSH Profiles, and stores a Hub login session. It is built to make each of those inspectable and reversible:

• Content-addressed Releases. A Release carries a sha256 hash. The CLI recomputes it and refuses mismatches.
• Pinned sources. npm bundles carry integrity hashes. GitHub bundles must reference a full commit.
• Explicit plans. Mutations expire after 30 minutes and fail if the local state changed since planning.
• Staged apply. Validation happens in a staging directory. Your live Profile is swapped only after it passes.
• Recoverable revisions. The previous Profile and lockfile are kept intact for rollback.
• Secrets stay local. profile share refuses patches containing credential-looking values and publishes only environment-variable references.
• Session storage. Tokens live in ~/.dsh/.hub/auth.json with mode 0600. The embedded WorkOS client ID is a public OAuth identifier.

Telemetry. After a first-run notice, lifecycle commands send anonymous, aggregate-only usage events (slug, version, outcome, error category, duration, platform, CLI version). No account, machine ID, path, config, or environment value is ever included. Disable it with dsh-hub telemetry off, --no-telemetry, DSH_HUB_TELEMETRY=0, or DO_NOT_TRACK=1. Full field list and retention policy: packages/cli/README.md.

To report a vulnerability, follow SECURITY.md.

Development

bash
corepack enable
pnpm install --frozen-lockfile
pnpm check        # typecheck + tests + package-content audit

packages/
  schemas/       zod contracts
  registry/      resolver + bundle ordering
  cli/           the dsh-hub command
  dsh-plugin/    agent tool adapter
skills/dsh-hub/  agent Skill
docs/            architecture, releasing

Tests use Node's built-in runner. After pnpm build, run a single package's suite with:

bash
node --test packages/cli/tests/*.test.ts

Release notes live in CHANGELOG.md and the release process in docs/releasing.md.

Contributing

Bug reports and pull requests are welcome. Start with CONTRIBUTING.md. By participating you agree to the Code of Conduct.

License

MIT

_{DSH Hub is an independent community project and is not affiliated with or endorsed by DeepSeek.}