CLI Reference¶

Bernstein ships a large surface of CLI commands registered in cli/main.py. This page is the single-source reference for every flag on every visible command. For driving Bernstein from a script, also read cli/task-lifecycle.md and cli/replay.md.

Find a command fast: Ctrl-F for the command name. Every entry below cites its source as cli/<file>:<line>. Get rich help in the terminal: bernstein --help (root rich-formatted help) and bernstein help-all (the same, exhaustive). Per-command help: bernstein <command> --help works on every visible command and group.

Root command flags¶

bernstein itself accepts these flags (defined at cli/main.py:482-572). Most of them only matter when invoked without a subcommand - i.e. when you run bernstein to start orchestration from bernstein.yaml or an inline --goal.

The hidden flags (--evolve, --max-cycles, --interval, --github, --headless, --yes) are visible via --help-all and via bernstein --evolve --help once you know they exist.

Any global flag may also be set via bernstein.yaml (e.g. budget: 5.00); the CLI flag wins on conflict.

Commands by category¶

The commands are organised below by purpose, not alphabetically. Use the table inside each category for quick lookup; the longer per-command entries follow for the highest-traffic commands.

Conventions¶

• Synopsis lines use [flags] where every visible flag is listed in the flag table below it.
• All commands accept the root-level --json / -v / -q flags.
• Hidden subcommands (task compose, task sync, etc.) are documented in the Hidden commands section at the end.
• Flags marked auth require a logged-in session (bernstein login).

Run & control¶

The "do work" commands. This is where most operators live.

bernstein run¶

Execute a plan file (or start orchestration with no plan).

Synopsis: bernstein run [PLAN_FILE] [flags]

The full flag list is large (28 flags inherited from the root group and re-exposed; see cli/run_bootstrap.py:533+). Most commonly used:

--max-cost-usd is a hard cap, separate from the soft --budget threshold model. It writes the value to BERNSTEIN_MAX_COST_USD before bootstrap; the orchestrator drains live agents and aborts when cumulative routed spend crosses the threshold. Precedence is BERNSTEIN_MAX_COST_USD > run_config.json > seed.budget_usd

default (0 = unlimited). Non-positive values normalise to 0.

bernstein stop¶

Graceful or force stop.

bernstein stop (no flag) sends SIGTERM to the orchestrator and waits for agents to finish their current step and persist artefacts. bernstein stop --force terminates everything immediately and runs orphan-recovery on the next start.

bernstein cancel¶

See cli/task-lifecycle.md#bernstein-cancel.

bernstein cleanup¶

bernstein replay¶

See cli/replay.md for full reference.

bernstein checkpoint¶

Snapshots .sdd/ state so a later bernstein run can resume from it.

bernstein wrap-up¶

End a session with a summary, retrospective, and learning capture. Hides under no flags; useful at the end of a long-running orchestration.

bernstein init / bernstein init-wizard¶

init-wizard adds an interactive prompt flow (project type, default agent, budget, etc.) and is preferred for first-time users.

Plan & tasks¶

bernstein plan¶

The graph view shows the critical path in bold yellow with a star (★) and lists bottlenecks at the bottom.

bernstein plan generate¶

bernstein plan compile¶

Compile a requirements document into a gated task graph. A three-stage pipeline with at most one model call: draft (structured requirement extraction), approve (the requirement-set hash is bound into the audit chain), and compile (a deterministic, model-free transformation to a task graph). Each task node carries the content hashes of the requirement lines it implements, so every artefact traces back to spec lines through lineage.

Artefacts are written to .sdd/spec/<name>/ (requirements.json, graph.json, and, with --approve, receipt.json). The same approved requirement set always compiles to a byte-identical graph, so graph_hash is reproducible; editing one requirement re-plans only the affected node while every other node keeps its content-addressed identity.

bernstein add-task¶

See cli/task-lifecycle.md#bernstein-add-task.

bernstein review¶

See cli/task-lifecycle.md#bernstein-review-bernstein-verify.

Status & monitoring¶

bernstein status¶

Compact one-screen project view.

bernstein live¶

The default is the 3-column Textual TUI: Agents | Tasks | Activity feed. --classic falls back to a single-pane Rich Live view.

bernstein dashboard¶

bernstein logs¶

A subcommand group; defaults to bernstein logs tail.

bernstein logs (no subcommand) is equivalent to bernstein logs tail.

bernstein recap¶

bernstein retro¶

bernstein watch¶

bernstein trace¶

Subcommands project RUN_ID and verify-projection RUN_ID emit and verify a signed OTel GenAI span set projected from the run event journal. Span ids are derived from journal entry hashes (byte-identical across replays), each span carries bernstein.journal.entry_hash, and the set is signed with the install identity. --no-genai-stability omits the Development-stage GenAI convention attributes while keeping the ids journal-anchored; the local .sdd/runs/<run_id>/projection.otel.json store emits even with no OTLP endpoint set. (cli/commands/advanced_cmd.py, core/observability/otel_projection.py.)

bernstein slo¶

Quality & autofix¶

bernstein verify¶

Verifies integrity and reproducibility artefacts. It does not run lint / test / type-check quality gates; use bernstein test and the project's configured quality gates for that.

bernstein autofix¶

bernstein autofix start flags include --workdir, --server URL, --poll SEC, --max-attempts N, --token. See cli/commands/autofix_cmd.py:172-200 for full list.

bernstein ci¶

Common flags: --token (env: GITHUB_TOKEN), --server, --interval. (cli/commands/ci_cmd.py:49+.)

bernstein chaos¶

Most subcommands accept --agent-id, --duration, --pattern as relevant. (cli/commands/chaos_cmd.py:32+.)

bernstein eval / bernstein benchmark¶

The two groups share most flags:

bernstein eval run is the typical command for SWE-bench-style evaluations; bernstein benchmark run for Bernstein-internal performance benchmarks. See cli/commands/eval_benchmark_cmd.py:127+ and :426+.

bernstein api-check¶

bernstein dep-impact¶

bernstein diff¶

Show what changed between two task states.

Adapters & agents¶

bernstein agents¶

bernstein test-adapter¶

bernstein worker¶

See operations/cluster-mode.md for the full setup walkthrough.

bernstein evolve¶

bernstein evolve is hidden behind a confirmation prompt by default - see the safety guard at cli/main.py:455.

Plugins & skills¶

bernstein plugins¶

Lists plugins in .bernstein/plugins/<name>/meta.json.

bernstein skills¶

The skills catalog ... subgroup browses, installs, searches, and upgrades skill packs from the registry. Other subcommands include bench, diff, lint, test, sync, and watch. (cli/commands/skills_cmd.py.)

bernstein skill¶

Usage-attestation surface for installed skills. Each catalog install anchors a lineage receipt in the run's Merkle+HMAC spine; provenance recomputes usage from verified journal heads rather than a stored counter.

SKILL is a catalog entry id (resolved via skills.lock) or a raw content digest. (cli/commands/skill_cmd.py.)

bernstein prompts¶

bernstein manifest¶

bernstein templates¶

Cloud & cluster¶

bernstein cloud¶

(cli/commands/cloud_cmd.py:35+.)

bernstein gateway¶

bernstein tunnel¶

(cli/commands/tunnel_cmd.py:62-117.)

bernstein remote¶

(cli/commands/remote_cmd.py:52-200.)

bernstein connect¶

bernstein fleet¶

Multi-project dashboard.

The group also accepts --web [host:]port to run the web view instead of the TUI. (cli/commands/fleet_cmd.py:50+.)

Auth & security¶

Task-level approve / reject are different commands - see Plan & tasks.

bernstein identity¶

Outbound agent-facing requests (A2A card fetch, browser/research rendering) carry an RFC 9421 Ed25519 signature keyed to the install-identity thumbprint. BERNSTEIN_HTTP_SIGNING_REQUIRED=1 turns an unsigned outbound path into a hard error. BERNSTEIN_AGENT_CARD_KEY_DIR overrides the key directory location.

bernstein delegation¶

bernstein login¶

(cli/commands/auth_cmd.py:145-146.)

bernstein auth¶

bernstein creds¶

(cli/commands/creds_cmd.py:214-282.)

bernstein policy¶

bernstein compliance¶

(cli/commands/compliance_cmd.py:26+.)

bernstein audit¶

(cli/commands/audit_cmd.py:25+. The slice verb is the deterministic-subset extractor described in HMAC-chained audit log.)

bernstein lineage¶

Every adapter artifact write is recorded, without per-adapter opt-in, as one Merkle-chained, HMAC-tagged entry in the run's lineage spine under .sdd/lineage/<run_id>/spine.jsonl (head hash in spine.head). The head hash is the run's artifact-provenance identity. Recording is gated by BERNSTEIN_LINEAGE_ENABLED (default on); when enabled it fails closed, so a write that cannot be recorded raises rather than dropping provenance. verify against an empty run reports a distinct NO ENTRIES status instead of passing trivially. (cli/commands/lineage_cmd.py, core/lineage/spine.py.)

bernstein credential¶

The manifest is a deterministic projection of the artifact's lineage entries: a hard-binding assertion (c2pa.hash.data) carries the spine entry's content hash and an actions assertion (c2pa.actions) records the producing model and actor. It is signed with the install-identity Ed25519 key, so one attestation root covers both who ran the artifact and what was produced. With no lineage entry for the artifact there is nothing to project, so emit fails rather than fabricating an unsigned label. Watermark and fingerprint soft-binding layers are pluggable via c2pa.soft-binding. Two replays of the same run produce byte-identical manifests. (cli/commands/credential_cmd.py, core/lineage/c2pa.py.)

bernstein compaction¶

Every context compaction (proactive threshold or reactive overflow recovery) is recorded as a compaction.receipt event in the HMAC-chained audit log and as a step in the worker's replay journal. log prints those receipts (trigger, token delta, validator verdicts, retry count, pre/post SHA-256). --verify re-runs the receipt verification: the HMAC chain must verify and every journaled compaction step must have a chain receipt with matching hashes; the command exits non-zero otherwise.

(cli/commands/compaction_cmd.py:32+.)

bernstein quarantine¶

(cli/commands/advanced_cmd.py.)

bernstein approve-tool / bernstein reject-tool¶

Tool-call approval gate. When an agent requests a sensitive tool call (network egress, file write outside its worktree, exec outside its sandbox), the orchestrator pauses and writes a request to .sdd/runtime/tool_approvals/. Resolve with these commands.

bernstein approve-tool <request_id>
bernstein reject-tool  <request_id>

Cost & tokens¶

bernstein cost¶

bernstein cost profile-report¶

Emits per-profile tasks / output tokens / USD / mean tokens per task plus joined verification pass rates. The artifact is canonical JSON named by its own SHA-256, embeds the ledger line-hash range it was computed from, and is appended to the audit chain, so anyone holding the ledger can recompute it byte-identically. Cross-profile savings are only claimed when both profiles have at least 5 tasks with the same role and model; otherwise the report states "insufficient comparable runs".

bernstein estimate¶

bernstein cost policy preflight¶

Cost-aware scheduling (issue #2354). Projects the spend ledger into named pools, compares each against its configured cap plus the planned run spend, and exits non-zero when any capped pool is (or would be) exhausted -- so pool exhaustion stops a run at the gate, not halfway through. Also reports the shipped price-table staleness advisory.

bernstein cost policy verify DECISION_HASH¶

Re-derives the decision hash from the stored dispatch receipt (catching a forged admit / zeroed overrun) and re-checks the lineage-spine anchor. A receipt that no longer recomputes fails exactly like a tampered chain entry.

Maintenance & debug¶

bernstein doctor¶

(cli/commands/advanced_cmd.py:536-550 re-exposes cli/status_cmd.py:doctor.)

bernstein debug-bundle¶

bernstein self-update¶

bernstein completions¶

eval "$(bernstein completions --shell bash)"
bernstein completions --shell zsh > ~/.zsh/completion/_bernstein

bernstein config¶

bernstein workspace¶

For worktree lifecycle (inspection / reaping) use bernstein worktrees list / bernstein worktrees gc.

bernstein session¶

bernstein memory¶

bernstein cache¶

(cli/commands/cache_cmd.py:45-146.)

bernstein notify¶

(cli/commands/notify_cmd.py:63+.)

bernstein triggers¶

bernstein dr¶

Disaster recovery; see operations/disaster-recovery.md.

bernstein daemon¶

systemd / launchd unit installer.

(cli/commands/daemon_cmd.py:76+.)

bernstein man-pages¶

bernstein config-path¶

Print the path Bernstein would read config from. Useful for shell completion and CI. No flags.

Integration & MCP¶

bernstein mcp¶

The root MCP command - runs Bernstein as an MCP server itself.

bernstein mcp catalog¶

See reference/mcp-catalog.md for the full reference.

bernstein chat¶

bernstein hooks¶

bernstein pr¶

(cli/commands/pr_cmd.py:183-220.)

bernstein review-responder¶

bernstein preview¶

(cli/commands/preview_cmd.py:46-220.)

Misc¶

bernstein ab-test¶

bernstein acp serve¶

bernstein fingerprint¶

(cli/commands/fingerprint_cmd.py:37+.)

bernstein graph¶

bernstein voice / bernstein listen¶

Experimental voice control (see operations/voice-control.md when published).

bernstein explain¶

bernstein ideate¶

bernstein test¶

Runs automated resilience tests with optional chaos injection. This is not a project test-suite runner; use bernstein.yaml: quality_gates.tests (and your configured test runner) for that.

bernstein wiki build¶

Renders a deterministic Markdown wiki from the AST symbol graph plus the agents.md IR. Streams to stdout by default. See Wiki build for the operator guide.

bernstein scaffold¶

First slice of the prompt-to-repo scaffolder. See Prompt-to-repo scaffold.

Hidden commands¶

Four task-related commands are wired but hidden from --help. They are stable and supported; just not surfaced because their UX is uneven or because their visible counterpart (bernstein add-task, bernstein logs) is what most users want.

To invoke any of them, just type the full path (bernstein task compose ...) - they accept the same flags as their visible siblings.

See also¶

• cli/task-lifecycle.md - driving Bernstein from a script.
• cli/replay.md - replay reference.
• reference/mcp-catalog.md - MCP catalog walkthrough.
• reference/openapi-reference.md - REST + WebSocket + ACP/A2A endpoints.
• reference/FEATURE_MATRIX.md - capability matrix.
• operations/CONFIG.md - every config key Bernstein recognises.

Endpoint certification: bernstein doctor --endpoint¶

Certify an OpenAI-compatible endpoint (a local runtime such as ollama, LM Studio, or an MLX server) for per-role use. The doctor runs a fixed conformance subset -- reachability, chat completion, tool calling, patch format fidelity, timeout behavior, context floor -- and prints a deterministic certify/reject verdict per role with machine reason codes. The result is sealed as a signed receipt under .sdd/endpoints/certifications/, anchored to the lineage spine, and mirrored into the audit chain; config validation gates merge-critical roles on it.

Exit codes: 0 every evaluated role certified, 1 at least one role rejected, 2 no model could be resolved.

bernstein doctor --endpoint http://127.0.0.1:11434/v1 --endpoint-engine ollama
bernstein doctor --endpoint http://127.0.0.1:11434/v1 --role manager

See Local endpoints for profiles, role tiers, and the verified-configuration table.

Provider failover drill¶

bernstein doctor --failover-drill¶

Probes every declared chain element and evaluates each chain position as the dispatch target under a simulated outage of its predecessors. Exits non-zero when any declared chain element is broken, and zero when all are healthy. Each drill row carries the deterministic routing-decision hash its simulated outage prefix would produce; drill outcomes are mirrored into the audit chain when a .sdd workspace is present. See Provider availability & failover.

Packaged agent skill: bernstein skills package¶

Bernstein ships a cross-vendor bernstein-run skill (open SKILL.md format) so agent sessions can drive orchestration without a separate shell. Installs are receipt-backed: each install anchors a content-addressed receipt in the skills lineage spine and mirrors a plugin.install_receipt event into the HMAC audit chain.

bernstein skills package show¶

Prints the bundled skill's content address, manifest hash, and the supported host list.

bernstein skills package install¶

Exit codes: 0 installed and anchored, 1 error.

bernstein skills package verify¶

Re-hashes the installed tree and proves it against the anchored receipt: the recomputed content address selects the receipt, then the install spine and the manifest hash are checked. A tampered tree resolves to a content address with no receipt, so the verdict is structural.

Exit codes: 0 verified, 1 missing directory, 2 attestation failure.

bernstein skills package update¶

Supersedes a previously attested install with new content. Unlike install --force (which overwrites and anchors an independent install receipt), update binds the prior content address to the new one: the update receipt is content-addressed by the new tree, anchored in the same skills lineage spine, and mirrored into the HMAC chain as a plugin.update_receipt event. A verifier walks the update receipts newest to oldest and lands on the root install, so the supersession history of an installed tree is reconstructable offline. A tree that was never anchored is refused (run install first).

Exit codes: 0 updated or already current, 1 error (missing or unattested install).

bernstein skills package status¶

Scans the default skill directory for each supported host and scope, re-hashes any present tree, and proves it against its anchored install or update receipt. --json emits the per-install verdicts as JSON; --home overrides the home directory for user-scoped destinations.

Exit codes: 0 every present install verifies (or none present), 2 at least one present install failed verification.

bernstein skills package conformance¶

Installs the bundled skill into every selected host against one shared install, then replays the skill's documented self-check contract (skills package show, then skills package verify --dest) per host. Each host runs the contract as it would from inside its own session; the per-host pass/fail table, the shared content address, and the aggregate verdict are sealed into a content-addressed conformance receipt anchored in the lineage spine and a plugin.conformance_receipt audit-chain event.

Options: --host (repeatable; defaults to every supported host), --scope (project/user), --min-hosts (green hosts required for an overall pass; default 3), --json, --workdir.

Exit codes: 0 every host green and the --min-hosts bar met, 2 conformance failed, 1 error.

bernstein skills package image-verify¶

Proves, offline, that the MCP registry listing (server.json) and the Docker MCP catalog entry (packaging/docker-mcp/server.yaml) resolve to the same canonical signed ghcr.io/<owner>/bernstein image and that the registry listing pins the release version, so a host cannot pull a different (or unsigned) image than the catalog advertises. With --online it additionally runs gh attestation verify against the live Sigstore build-provenance attestation.

Options: --version (the release version the image must pin; defaults to the installed bernstein version), --online, --json, --repo-root.

Exit codes: 0 consistent (and, with --online, attestation verified or tooling unavailable), 2 a manifest mismatch or a failed online attestation.

bernstein skills package install --host claude --scope project
bernstein skills package install --dest ~/.claude/plugins/bernstein --record-only
bernstein skills package verify --host claude --scope project
bernstein skills package update --host claude --scope project
bernstein skills package status
bernstein skills package conformance --host claude --host codex --host cursor

See Agent sessions for the skill body, per-host notes, and the registry listings generated at release time.

Dashboard authentication: bernstein auth dashboard-token¶

The dashboard (bernstein gui serve, /dashboard on the task server) accepts two credential kinds: a password (BERNSTEIN_DASHBOARD_PASSWORD or the dashboard_auth block in bernstein.yaml) and scoped tokens issued here. Tokens carry a principal and a scope: viewer reads every surface and can change nothing; operator can also trigger state-changing actions.

Grants live in an append-only journal of HMAC-signed rows (.sdd/auth/dashboard_tokens.jsonl) that stores only the token's SHA-256 digest - the raw token is printed once at issue time. Editing a row (for example widening viewer to operator) breaks its signature and the token stops validating. Every issue and revoke is mirrored onto the audit chain (dashboard.token_grant), and every login and write authorization is a signed governance decision in the dashboard-auth lineage run - recompute them offline with bernstein governance verify dashboard-auth.

All subcommands accept --workdir (default .) pointing at the project root containing .sdd/.

bernstein auth dashboard-token issue --principal alice --scope viewer
bernstein auth dashboard-token list
bernstein auth dashboard-token revoke 3f1a9c2d5e7b0a41
bernstein governance verify dashboard-auth

Startup posture: bernstein gui serve on a loopback host without any credential configured issues an operator token and prints it once; on a non-loopback host it refuses to start until a token or password is configured. There is no silent open mode on a routable interface. Use the token as Authorization: Bearer <token> or in the dashboard login form (POST /dashboard/auth/login); the session cookie inherits exactly the token's principal and scope.

SPIFFE workload identity: bernstein spiffe¶

Infrastructure teams standardizing on SPIFFE workload identity can consume Bernstein workloads directly. The Ed25519 install identity and each agent card map onto a deterministic SPIFFE ID; when a SPIRE agent is present (optional bernstein[spiffe] extra) its X.509-SVID is bound to a card by a receipt anchored in the HMAC audit chain. The self-contained Ed25519 path stays the default with the extra absent.

SPIFFE ID scheme (deterministic):

spiffe://<trust-domain>/bernstein/<install>/<agent>

• <trust-domain>: operator SPIFFE trust domain (validated, lowercase DNS-like).
• <install>: 16-hex fingerprint of the install public key (SHA-256 prefix).
• <agent>: the agent card id.

Two operators deriving the id for the same install and agent obtain the same string, and a verifier re-derives it later to check a card-to-SVID binding.

bernstein spiffe id \
    --install-key .bernstein/keys/agent-card.ed25519.pub \
    --agent backend-1 --trust-domain example.org
# -> spiffe://example.org/bernstein/<install>/backend-1

bernstein spiffe verify-binding binding.json \
    --install-key .bernstein/keys/agent-card.ed25519.pub \
    --trust-domain example.org --audit-dir .sdd/audit
# -> valid (chain-anchored)

The card-to-SVID binding is the receipt: bind_svid_to_card records a spiffe.svid_binding event pinning the binding content hash, the derived SPIFFE ID, the install fingerprint, the card hash, and the leaf SVID content address -- never the SVID private key. A post-hoc tamper to the binding fails verify-binding because its recomputed content hash no longer matches the chained receipt. SVID material also projects onto the cluster mTLS config, so the task server enforces mutual TLS through its existing uvicorn --ssl path. See SPIFFE workload identity for an example SPIRE configuration and threat-model notes.

In-process verification gate: bernstein hook-gate¶

A gate-capable adapter (Claude Code) wires its worker's PreToolUse and Stop hooks to bernstein hook-gate check. The command reads the hook event JSON on stdin, loads the task's persisted policy (.sdd/runtime/hook_gate/<session>.json, written at spawn from the task's owned_files and required evidence_producers), and enforces it in-session:

# Invoked by the worker's hook runner, not by hand:
bernstein hook-gate check --session <id> --event PreToolUse < event.json
bernstein hook-gate check --session <id> --event Stop < event.json

Trust model: the in-process gate is defence in depth and a cost optimisation. The scheduler-side evidence gate stays authoritative and runs regardless. A gate receipt IS an evidence bundle (bernstein evidence show / verify, bernstein audit verify), so a verifier cannot tell from the schema whether the gate fired in-process or scheduler-side. An adapter with no blocking hook surface injects no gate hooks and degrades to the scheduler-side gate with no policy weakening.

bernstein tournament¶

Tournament runs: parallel attempts selected by deterministic evaluators (#2353).

Selection is a pure function of the evaluator outputs (test pass rate, lint status, coverage delta, mutation score, arbitrary commands) with a stable attempt-hash tie-break, so replaying the run reproduces the identical decision. Fan-out is gated on the task's existing per-ticket budget ceiling and aborts with a clear error before spawning when projected spend would breach the cap.