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 (see bernstein run --help and cli/run_bootstrap.py:533+). Most commonly used:

The merge strategy is not a run flag: set merge_strategy: pr|direct in bernstein.yaml (default pr).

--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.

Non-interactive output (pipes, CI). When stdout is not a terminal the CLI detaches after bootstrap instead of opening the dashboard. Before exiting it waits up to ~10 seconds for the first spawn outcome:

• If the first spawn attempt was refused or errored before any work started, the failure reason is printed and the command exits 1. Details: bernstein status or .sdd/runtime/retrospective.md.
• Otherwise the summary is followed by an explicit detach notice; the run continues in the background and the command exits 0. Check progress with bernstein status.

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.

bernstein task¶

A group, with four subcommands. A task that must wait on something outside the run - a mid-flight approval, an external review, a credential rotation, a dependency landing - can be parked rather than left holding its resources: the park writes an attested receipt, releases the seat, sandbox and budget headroom, and resume restores from that receipt.

The group itself takes no flags beyond --help; each subcommand carries its own, below.

bernstein task complete¶

Resolves the task-server URL and the session token itself, from BERNSTEIN_SERVER_URL / .sdd/runtime/server.port and BERNSTEIN_AUTH_TOKEN / the persisted run-token file, so a completion does not have to be hand-assembled as a request with a bearer header.

bernstein task suspend¶

bernstein task resume¶

bernstein task list-suspended¶

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.

Both views resolve the task server the same way as the rest of the CLI: BERNSTEIN_SERVER_URL, then the port the running orchestrator persisted in .sdd/runtime/server.port, then http://localhost:8052. When the poll cannot reach that server the header says No connection to <url> rather than drawing empty panels, which would be indistinguishable from an orchestrator with nothing to do. That state means every read failed: one route erroring while the others answer is a broken route, not a dead server, so the dashboard keeps rendering the panels that did load.

The run token the orchestrator persists under .sdd/runtime is only ever sent to a loopback address: it is a credential this machine minted for its own run, and BERNSTEIN_SERVER_URL can name any host. A token you set in BERNSTEIN_AUTH_TOKEN yourself goes wherever you point the dashboard.

bernstein logs¶

A subcommand group; defaults to bernstein logs tail.

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

bernstein recap¶

With --since the summary is the "since you were away" report: completed and failed tasks, provider errors, and estimated cost read from .sdd/ alone, so it still answers what happened after the run and its server have exited.

bernstein retro¶

bernstein runs¶

Group over the runs recorded in the work ledger.

bernstein runs report¶

The report is projected from .sdd/ alone, so it still answers what came of a batch of runs after the orchestrator and its task server have exited. Each row carries the outcome class and the one line of evidence it was classified from: pr-opened (a branch was published), gate-failed (a quality gate blocked the run), no-changes (zero commits over base), infra-error (adapter or transport death, or no wrap-up was ever recorded), and wedged (the run ended with open tasks nothing could spawn).

bernstein watch¶

bernstein trace¶

Group: inspect, serve, and verify local agent traces.

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¶

Group: 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¶

See cli/commands/autofix_cmd.py:172+ for the full flag list.

bernstein ci¶

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

bernstein chaos¶

agent-kill accepts --agent-id, file-remove accepts --pattern, and status accepts --limit. (cli/commands/chaos_cmd.py:33+.)

bernstein eval¶

Group: evaluation pipelines. The subcommands carry the flags; the group itself only accepts the reliability options listed below.

bernstein eval run is the typical command for SWE-bench-style evaluations; bernstein eval swe-bench and bernstein eval golden cover the harness and the curated golden suite. See cli/commands/eval_benchmark_cmd.py:127+ and :426+.

bernstein eval additionally accepts group-level reliability options — a pass^k alias for bench run --reliability that cannot be combined with an eval subcommand:

Verification stays on bernstein bench reliability-verify / bernstein bench reliability-check. (cli/commands/eval_benchmark_cmd.py:800+.)

bernstein benchmark (deprecated)¶

bernstein benchmark is a deprecated alias for bernstein eval and prints a warning on stderr before running; it keeps every subcommand it carried and is removed in v4.0.0. The group itself takes no flags — including the reliability options above, which are eval-only. Every subcommand name is reachable under eval before the removal:

One capability does not survive the rename: bernstein benchmark run --benchmarks-dir DIR runs the evolution benchmark tree and eval run cannot. Until that option is ported onto an eval command, bernstein benchmark run is the only spelling for it, and v4.0.0 should not unregister the alias without porting it first. tests/unit/test_fold_benchmark_subcommands.py declares the list of alias-only options and fails if it widens or if a declared replacement stops being accepted, so this note cannot silently go stale.

eval simulate is not the top-level bernstein simulate. The top-level command is a digital-twin simulation of a plan against historical traces (--plan, --from-traces, --traces-dir); eval simulate replays the standard benchmark task set for throughput, cost and quality (--tasks-dir, --task-id, --baseline). They share a verb and no options, and the top-level command is unaffected by this change. bernstein bench is a separate command and is not folded in.

bernstein impact¶

Change-impact analysis for a working tree. Three subcommands, each answering a different question about the same change.

bernstein impact api --base main     # do the changed files break their own signatures?
bernstein impact deps --base main    # which callers elsewhere in the repo break?
bernstein impact blast score --file src/db/migrate.py   # how irreversible is it?

bernstein impact api¶

Compares Python function signatures between the working tree and a base ref. Exits 1 when breaking changes are found.

bernstein impact deps¶

Finds every call site in the repository that the changed signatures break.

bernstein impact blast¶

Group. score scores a change described on the command line; show TASK_ID pretty-prints a saved report from .sdd/metrics/blast_radius/.

bernstein api-check¶

Second spelling of bernstein impact api. Same flags, same exit codes.

bernstein dep-impact¶

Deprecated alias of bernstein impact deps, kept registered through the 3.x line and removed in v4.0.0. Prints a deprecation notice to stderr, then runs bernstein impact deps with the arguments it was given, so --json output on stdout stays parseable.

bernstein blast-radius¶

Deprecated alias of bernstein impact blast, kept registered through the 3.x line and removed in v4.0.0. Exposes the same score and show subcommands and prints a deprecation notice to stderr before running them.

bernstein diff¶

Show the diff an agent produced for a task, resolved from its live worktree, its merged branch, or the merge commit.

Adapters & agents¶

bernstein agents¶

bernstein test-adapter¶

bernstein worker¶

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

bernstein evolve¶

Preview: bernstein evolve run is not a zero-workspace first-run path. In a clean directory it exits before starting the evolution loop because .sdd/ is missing. Initialise a Bernstein workspace first, then run the command from that workspace.

Group: self-evolution proposals and their review lifecycle. See Evolve CLI for the run-ledger to draft to issue contour and the dry-run flow.

Plugins & skills¶

bernstein plugins¶

Lists plugins in .bernstein/plugins/<name>/meta.json with a trust tier and score derived from the plugin's own signals - signature file, packaging metadata, README, tests - so an unreviewed plugin is visible before it loads.

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. Both also accept --tool <id> to resolve tool-call approvals (the flag form of approve-tool / reject-tool).

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.

identity agents is a projection, not a directory: deleting the rendered output and rebuilding it from the same chain at the same --as-of instant reproduces identical bytes, and a run whose chain does not verify contributes no principals at all.

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). JSON receipt objects also include policy_version; legacy and unversioned records use the empty string. --verify re-runs the receipt verification: the HMAC chain must verify and every journaled compaction step must have a chain receipt with matching hashes and policy version; the command exits non-zero otherwise. A missing policy-version key on both sides of a legacy receipt/journal pair is treated as the empty string for backward-compatible verification.

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

bernstein quarantine¶

Reads and writes .sdd/runtime/quarantine.json, the cross-run quarantine the orchestrator maintains, so neither subcommand needs a running task server.

(cli/commands/advanced_cmd.py.)

bernstein security-review¶

Pattern-scans a unified diff without calling a model. Exit 0 clean or advisory-only, 1 on any critical/high finding, 2 when there is no diff.

bernstein pool¶

Define and govern named sandbox pools projected from the HMAC audit chain.

Deliberate distinction (#3138): bernstein pool defines and verifies execution sandbox environments (backends, capability ceilings, egress classes, templates) projected from the HMAC audit chain (.sdd/audit/) and content-addressed store (.sdd/sandbox/). It is distinct from bernstein limits pool, which manages admission slot concurrency in the hash-chained admission work ledger (.sdd/admission/).

bernstein limits¶

Named resource pools with lease-backed admission (verify, status, CRUD) projected from the admission work ledger.

Deliberate distinction (#3138): bernstein limits pool manages lease-backed concurrency slot pools in the admission work ledger (.sdd/admission/). It is distinct from bernstein pool, which defines sandbox execution environments in the HMAC audit chain.

bernstein admission¶

Check the executor admission policy declared in bernstein.yaml without spawning anything. The gate itself runs inside the spawner, so without this command an operator only learns a role is refused when a run reaches it.

A config with no admission: block reports that no policy is declared and exits 0. See Executor admission policy for the rule model and a worked example.

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 --id <request_id>
bernstein reject-tool  --id <request_id>
# Flag form (the aliases above stay registered through the 3.10 line,
# unregistered in 4.0.0):
bernstein approve --tool <request_id>
bernstein reject --tool <request_id>

With no identifier, the oldest pending approval is resolved.

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 cost 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 gc cas¶

Mark-and-sweep of the content-addressed store. Referenced digests are collected from the durable roots -- the write-ahead log, snapshots, audit seals, lineage records and the backlog -- so a blob reachable from any of them survives regardless of its age. Exits non-zero if the sweep fails.

bernstein doctor¶

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

bernstein debug bundle¶

bernstein debug-bundle (deprecated)¶

The older, separate builder. Removed in v4.0.0; bernstein debug bundle does not accept these flags.

bernstein self¶

See Updates: check, verify, apply.

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 the bernstein worktrees group below.

bernstein worktrees¶

bernstein worktrees graph¶

Render one fan-out's sealed run graph, branch by branch, from the receipt under .sdd/run-graph/.

Exits non-zero when a branch's spine no longer verifies, or when --verify refuses the receipt. A branch with no --run-id is reported as unresolved, not as failing: it was not checked, so it did not fail.

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¶

The title names the commit that changed the most under src/; merge, [WIP], style:/chore:, formatter and lint-repair commits and generated-context-file syncs are excluded, so a run that ends with upkeep is still titled after the change it made. The body is composed from the linked issue's problem statement, the files the diff touches and the gates that ran, and carries a Provenance block naming the diff hash and the run's journal head; bernstein review-receipt verify recomputes both and rejects a description whose diff has since changed.

(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 govern¶

bernstein govern inventory¶

See govern inventory --render.

bernstein listen¶

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

bernstein explain¶

bernstein test¶

Runs automated resilience tests. 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¶

Three task-related commands carry hidden=True, so they do not appear in --help. They are stable and supported, and each is registered at the top level -- not under bernstein task. The spellings below are the ones that resolve.

A command's declared name and its registered name differ here, so the declared spelling is not an invocation: bernstein task compose and bernstein task parts resolve to nothing. Type the names in the table.

bernstein task itself is a real group and is not hidden - it carries the durable lifecycle subcommands documented under Plan & tasks. It is only these three that are not under it, despite their declared names suggesting otherwise.

task_cmd.py also declares a notes command (_notes_legacy, cli/commands/task_cmd.py:753) that is registered nowhere and therefore cannot be invoked at all. To tail server / spawner logs, use bernstein logs.

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.