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
| Command | Purpose | Exit codes |
|---|---|---|
npm run doctor | Read-only multi-location diagnosis of rosters, workspaces, bindings, config membership, dispatch-ledger invariants, and native state. | 0, 1, 2 |
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. | 0, 1, 2 |
npm run backup | Export, restore, roll back, or inspect the durable plugin state and derived workspace config. | 0, 1, 2 |
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. | 0, 2 |
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. | 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
npm run doctor -- --json /path/to/projectOptions
| Option | Effect |
|---|---|
--json | Emit 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. |
--help | Show command help. |
Exit codes
| Code | Meaning |
|---|---|
0 | All requested locations agree. |
1 | Divergence found. |
2 | Usage, 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
:logsviewer 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
npm run data -- export /path/to/project --out ensemble-export.json
npm run data -- delete /path/to/project --confirm DELETEOptions
| Option | Effect |
|---|---|
--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 DELETE | Required for delete. |
--logs | Delete local Ensemble log files for all workspaces. |
--delete-native-sessions | Also ask the host to remove bound native sessions. |
--json | Emit a machine-readable delete report. |
--server <url> | Override the service URL. |
--service-file <path> | Override the service descriptor path. |
Exit codes
| Code | Meaning |
|---|---|
0 | The command completed. |
1 | The service refused the request, for example a bad confirmation token. |
2 | Usage, connection, descriptor, or response failure. |
Notes
- Export format is
ensemble.data-exportversion 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
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
| Option | Effect |
|---|---|
--out <file> | Export destination. Written atomically with mode 0600. |
--in <file> | Backup document to restore. |
--confirm RESTORE | Required for restore. |
--confirm ROLLBACK | Required for rollback. |
--server <url> | Override the service URL. |
--service-file <path> | Override the service descriptor path. |
--json | Print one machine-readable report. |
Exit codes
| Code | Meaning |
|---|---|
0 | The command succeeded. |
1 | The service refused the command. |
2 | Usage, 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
npm run support:bundle -- --out ./ensemble-support --directory /path/to/projectOptions
| Option | Effect |
|---|---|
--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. |
--json | Print the manifest to stdout. |
Exit codes
| Code | Meaning |
|---|---|
0 | The bundle was written. |
2 | Usage, 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
npm run logs:summary -- --level warn
npm run logs:summary -- --json --since 2026-11-17T00:00:00ZOptions
| Option | Effect |
|---|---|
--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. |
--json | Print the full machine-readable summary. |
Exit codes
| Code | Meaning |
|---|---|
0 | Summary written. |
2 | Missing log directory or invalid arguments. |
Notes
- No service connection is required; this reads local files.
- An unknown
--levelis 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.
| Command | Purpose |
|---|---|
issue:hygiene | Read-only GitHub listing of parent issues whose sub-issues are all closed. Never edits or closes issues. |
docs:check | Full 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:fast | Pull-request docs gate: Markdown lint and source checks without the VitePress build; the Docs site workflow owns the site build. |
docs:lint | Run markdownlint-cli2 with the repository's minimal structural rules. |
docs:reference | Regenerate the reference pages from the code catalogs. |
verify | Typecheck plus the unit test suite. |
test | Unit tests only. |
check | TypeScript typecheck only. |
build | Build the published package. |
check:build | Build plus the published-file check. |
docs:reference:check | Standalone generated-reference check. |
docs:site:anchors | Crawl 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. |
soak | The four-hour enforced fake-host soak gate; nightly or opt-in. |
soak:smoke | The 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
| Option | Applies to | Meaning |
|---|---|---|
--server <url> | doctor, data, backup, support bundle | Override the service URL. |
--service-file <path> | doctor, data, backup, support bundle | Override the service descriptor path. |
--help | All commands | Show help and exit. |
--json | doctor, data, backup, support bundle, logs summary | Print a machine-readable report. |
Next
- Files and storage: what data export and backup cover.
- Supported hosts and versions: the hosts these commands are verified on.