Skip to content

Operator CLI ​

These commands run from an Ensemble source checkout unless a row says otherwise. All service-backed clients resolve the same OpenCode service descriptor, accept --server and --service-file, honor OPENCODE_PASSWORD, and never print credentials.

Examples use /path/to/project as a placeholder for the workspace directory; $PWD means the current directory.

Command summary ​

CommandPurposeExit codes
npm run doctorRead-only multi-location diagnosis of rosters, workspaces, bindings, config membership, dispatch-ledger invariants, and native state.0, 1, 2
npm run dataExport one workspace's documented data projection or delete one workspace's Ensemble data while keeping the workspace, roster, and config usable.0, 1, 2
npm run backupExport, restore, roll back, or inspect the durable plugin state and derived workspace config.0, 1, 2
npm run support:bundleCollect a local, redacted evidence bundle: manifest, doctor report, log summary, bounded recent logs, log inventory, and a redacted service descriptor.0, 2
npm run logs:summaryRead-only summary of local JSONL logs by role, instance, level, event, task, dispatch group, failures, and feed reset/gap counts.0, 2

npm run doctor ​

Read-only multi-location diagnosis of rosters, workspaces, bindings, config membership, dispatch-ledger invariants, and native state.

npm run doctor -- [--json] [--server <url>] [--service-file <path>] <directory>...

Examples ​

sh
npm run doctor -- --json /path/to/project

Options ​

OptionEffect
--jsonEmit one machine-readable report without credentials.
--server <url>Override the service URL. Do not put credentials in the URL.
--service-file <path>Override the OpenCode service descriptor path.
--helpShow command help.

Exit codes ​

CodeMeaning
0All requested locations agree.
1Divergence found.
2Usage, connection, snapshot, or config-read failure.

Notes ​

  • Calls only the read-only diagnostic RPC. It does not call invoke, write storage, or write .ensemble/config.json.
  • The host may still reconcile while answering the snapshot, so reads are sequential and not atomic.
  • A package-only install has the in-app :logs viewer and host logs but no checkout-based doctor.

npm run data ​

Export one workspace's documented data projection or delete one workspace's Ensemble data while keeping the workspace, roster, and config usable.

npm run data -- export <directory> [--out <file>] [--workspace <id>] [--server <url>] [--service-file <path>]

Examples ​

sh
npm run data -- export /path/to/project --out ensemble-export.json
npm run data -- delete /path/to/project --confirm DELETE

Options ​

OptionEffect
--out <file>Write the export to an owner-only file instead of stdout.
--workspace <id>Select one workspace; otherwise the directory's workspace is used.
--confirm DELETERequired for delete.
--logsDelete local Ensemble log files for all workspaces.
--delete-native-sessionsAlso ask the host to remove bound native sessions.
--jsonEmit a machine-readable delete report.
--server <url>Override the service URL.
--service-file <path>Override the service descriptor path.

Exit codes ​

CodeMeaning
0The command completed.
1The service refused the request, for example a bad confirmation token.
2Usage, connection, descriptor, or response failure.

Notes ​

  • Export format is ensemble.data-export version 1. It excludes binding ids, paths, model configuration, settings, credentials, and logs.
  • Delete removes conversations, Work, memories, approvals, and queued direct sends for that workspace.
  • Without --delete-native-sessions, the host may still hold the original session history.

npm run backup ​

Export, restore, roll back, or inspect the durable plugin state and derived workspace config.

npm run backup -- export --out <file> <directory> | restore --in <file> --confirm RESTORE <directory> | rollback --confirm ROLLBACK <directory> | status <directory>

Examples ​

sh
npm run backup -- export --out ./ensemble-backup.json "$PWD"
npm run backup -- status "$PWD"
npm run backup -- restore --in ./ensemble-backup.json --confirm RESTORE "$PWD"
npm run backup -- rollback --confirm ROLLBACK "$PWD"

Options ​

OptionEffect
--out <file>Export destination. Written atomically with mode 0600.
--in <file>Backup document to restore.
--confirm RESTORERequired for restore.
--confirm ROLLBACKRequired for rollback.
--server <url>Override the service URL.
--service-file <path>Override the service descriptor path.
--jsonPrint one machine-readable report.

Exit codes ​

CodeMeaning
0The command succeeded.
1The service refused the command.
2Usage, file, descriptor, or connection failure.

Notes ​

  • A backup contains conversation content and workspace state. Keep it private and never commit it.
  • Restore and rollback refuse while work is running. A restore writes one pre-restore rollback slot.
  • The backup format is ensemble.backup; do not use a data export to restore a workspace.

npm run support:bundle ​

Collect a local, redacted evidence bundle: manifest, doctor report, log summary, bounded recent logs, log inventory, and a redacted service descriptor.

npm run support:bundle -- --out <dir> [--directory <path>]... [--server <url>] [--service-file <path>] [--log-dir <dir>] [--json]

Examples ​

sh
npm run support:bundle -- --out ./ensemble-support --directory /path/to/project

Options ​

OptionEffect
--out <dir>Required. Bundle directory, created when missing.
--directory <path>Workspace to diagnose. Repeatable; defaults to the current directory.
--server <url>Override the service URL.
--service-file <path>Override the service descriptor path.
--log-dir <dir>Override the Ensemble log directory.
--jsonPrint the manifest to stdout.

Exit codes ​

CodeMeaning
0The bundle was written.
2Usage, collection, or write failure.

Notes ​

  • No upload and no telemetry. Review the files before attaching them to an issue.
  • Conversation content, titles, instructions, prompts, file bytes, credentials, and home/state paths are omitted or redacted.

npm run logs:summary ​

Read-only summary of local JSONL logs by role, instance, level, event, task, dispatch group, failures, and feed reset/gap counts.

npm run logs:summary -- [--dir <dir>] [--since <iso>] [--level <level>] [--event <prefix>] [--task <id>] [--group <id>] [--json]

Examples ​

sh
npm run logs:summary -- --level warn
npm run logs:summary -- --json --since 2026-11-17T00:00:00Z

Options ​

OptionEffect
--dir <dir>Log directory; defaults to $XDG_STATE_HOME/ensemble/logs.
--since <iso>Only rows with ts at or after the ISO timestamp.
--level <level>Minimum level: error, warn, info, debug, or trace.
--event <prefix>Only events equal to or starting with the prefix.
--task <id>Only rows carrying the task id.
--group <id>Only rows for one dispatch group or its continuation lineage.
--jsonPrint the full machine-readable summary.

Exit codes ​

CodeMeaning
0Summary written.
2Missing log directory or invalid arguments.

Notes ​

  • No service connection is required; this reads local files.
  • An unknown --level is an error rather than a silent fallback.

Maintainer-only commands ​

These are repository tooling. They are not part of the published package's user surface.

CommandPurpose
issue:hygieneRead-only GitHub listing of parent issues whose sub-issues are all closed. Never edits or closes issues.
docs:checkFull local docs gate: Markdown lint, page inventory, frontmatter, links and VitePress-rendered anchors, shell syntax, contract/host/Node claims, generated reference, media, docs-site build, and built-anchor crawl.
docs:check:fastPull-request docs gate: Markdown lint and source checks without the VitePress build; the Docs site workflow owns the site build.
docs:lintRun markdownlint-cli2 with the repository's minimal structural rules.
docs:referenceRegenerate the reference pages from the code catalogs.
verifyTypecheck plus the unit test suite.
testUnit tests only.
checkTypeScript typecheck only.
buildBuild the published package.
check:buildBuild plus the published-file check.
docs:reference:checkStandalone generated-reference check.
docs:site:anchorsCrawl the built VitePress HTML and validate every internal fragment target.
test:live:*Live, fake, install, latency, lifecycle, and subagent verification suites.
benchmark:*Tool-surface and synthesis benchmarks.
soakThe four-hour enforced fake-host soak gate; nightly or opt-in.
soak:smokeThe short observe-only soak smoke run.

scripts/release-guard.mjs is the release preflight. It validates the tag, package version, and changelog before a release.

Common options ​

OptionApplies toMeaning
--server <url>doctor, data, backup, support bundleOverride the service URL.
--service-file <path>doctor, data, backup, support bundleOverride the service descriptor path.
--helpAll commandsShow help and exit.
--jsondoctor, data, backup, support bundle, logs summaryPrint a machine-readable report.

Next ​

Released under the MIT License.