CLI and configuration

Harmony extends the existing dsh launcher. Commands use the Web profile unless --profile <name> selects another one. Add --json where supported for machine-readable output.

Interactive terminal

dsh harmony
dsh harmony --profile tui

Press Tab to switch between Provider and Patch views. The TUI supports ordering, automatic sorting, Patch and Provider enablement, inspection and live reload.

Status and inspection

dsh harmony status [--json] [--profile <name>]
dsh harmony inspect [package] [--file <file>] [--patch <provider/id>] [--summary] [--json] [--profile <name>]

status prints every collected Patch and exits with code 1 if a Patch failed or an ordering or reload error remains. inspect prints the original source, each ordered intermediate result and the final source. --summary omits source text; --patch keeps only the targets touched by one stable Patch key.

Enablement

dsh harmony disable <provider/id> [--json] [--profile <name>]
dsh harmony enable <provider/id> [--json] [--profile <name>]
dsh harmony disable-provider <provider> [--json] [--profile <name>]
dsh harmony enable-provider <provider> [--json] [--profile <name>]

Provider-wide enablement uses an independent provider/* flag. It never clears or creates individual Patch flags, so re-enabling a Provider preserves Patches that were individually disabled.

Order

dsh harmony patch-order show [--json] [--profile <name>]
dsh harmony patch-order move <patch> (--before|--after) <patch> [--json] [--profile <name>]
dsh harmony patch-order auto [--json] [--profile <name>]

dsh harmony provider-order show [--json] [--profile <name>]
dsh harmony provider-order move <provider> (--before|--after) <provider> [--json] [--profile <name>]
dsh harmony provider-order auto [--json] [--profile <name>]

show exits with code 1 when the current list violates constraints. auto minimizes violations and preserves the existing relative order where possible. Moving a Provider regroups its Patches; moving a Patch preserves its exact cross-provider position.

Reload

dsh harmony reload [provider] [--json] [--profile <name>]

Reload requires a running Host. Omitting the Provider reloads the current graph. Harmony refuses to hot-reload its own Host entry from inside that runtime; restart DSH when such a change is required.

Profile state

Each profile stores Harmony state at:

$DSH_HOME/profiles/<name>/harmony.json

The file contains:

• order: the coarse Provider list;
• patchOrder: every registered stable Patch key once, in runtime order;
• disabled: individual provider/id keys and independent Provider-wide provider/* entries.

Harmony inserts and removes entries as declarations change. Do not edit this file directly while the profile is running. Settings, the TUI and non-interactive commands preflight updates and commit them transactionally.

Provider metadata

{
  "dsh": {
    "plugin": {
      "compatibility": {
        "requires": { "base-provider": "^2.0.0" },
        "conflicts": { "legacy-provider": "*" },
        "integrates": { "optional-renderer": "^1.0.0" }
      }
    },
    "harmony": {
      "patches": ["./patches/a.cjs", "./patches/b.cjs"],
      "after": ["provider-a"],
      "before": ["provider-c"]
    }
  }
}

dsh.harmony.before and after are ordering preferences, not dependencies. dsh.plugin.compatibility is shared DSH plugin metadata: requires, conflicts and integrates map package names to semver ranges and only report relationships. They never change plugin state or block startup.

Environment

Variable	Purpose
DSH_HOME	Overrides the Harness home containing profiles and Harmony state
DSH_HARMONY_DSH_ENTRY	Selects an explicit official @deepseek-ai/dsh/lib/bin.js, mainly for Desktop integration
DSH_HARMONY_PERF=1	Logs one structured timing record per startup or update

Performance records include prepareMs, transformMs, hostReloadMs, clientRebuildMs and totalMs. Diagnostics tools can subscribe to the dsh-harmony:load diagnostics_channel channel without enabling log output.

Stable Patch keys

Harmony combines the Provider package name and Patch id:

provider-package/patch-id

Status, enablement, ordering, inspection and errors use this key.