Skip to content
Not released yet. SuperBench is an experimental single-host prototype under active development. Nothing is released or supported for use yet. These docs describe themain branch and will be refreshed at the first release.

bench CLI

wet paint: New or experimental.Open as Markdown

bench is the command-line front door. Every command takes its flags before the task key. Output is JSON. With --socket, an operation goes to benchd and prints the versioned API result; without it, the command works directly on the local state and data directories and prints the engine’s own format. This page is checked against cmd/bench when the docs build.

There is no supported installation yet. bench version prints dev for a build from a branch.

Command What it does
create Register a task worktree from --repo on its task branch and prepare it.
recover Rebuild a bench from its remote-confirmed task branch (--repo, --branch) into empty state.
lease Grant the bench to --holder and print its token once. Refreshes the shared mirror first.
checkpoint Push the existing HEAD without force and confirm the remote has exactly that commit.
release Free the bench. Needs a clean, checkpointed, still-confirmed worktree.
status Read one bench, or all of them. Read-only; never migrates.
run bench run [flags] KEY -- COMMAND [ARGS]: lease and run one fenced command (Linux).
stop Fence the holder’s supervised execution; --admin stops it without the token (local operator).
setup Run the repository’s preparation in a fenced execution (Linux).

These work on local state only, as the trusted service owner, with the same --state and --data the daemon uses.

Command What it does
create-cold Register a checkout without setup. Never a fallback from a failed create.
recover-cold Recover without setup.
lease-repair A maintenance lease that skips the mirror refresh.
migrate Upgrade the state schema explicitly.
configure-host Record host storage settings: quota helper, free-space minimums, log budgets.
host-status Read host storage and admission state.
archive Freeze a released, clean, confirmed bench read-only (--archive-grace).
plan-reap Print the concrete deletion plan for an archived bench.
reap Delete exactly the approved plan (--plan, --approve) after the grace period.
archive-run One sweep of automatic archive candidates (--limit, --after-key).
history Run history for one bench, or all.
inspect-log, adopt-log, reconcile-log Inspect, adopt or reconcile a retained run log.
plan-collect, collect, resume-collect, cancel-collect, collections Reviewed log collection.
retention-preview, retention-enable, retention-disable, retention-status, retention-run, retention-ack-pending The automatic log retention policy, off until enabled.
prepare-local, acknowledge-local-preparation, local-preparation-status Cooperative preparation without Linux fencing.
handoff Reviewed cross-host transfer: offer, inspect-export, begin-export, continue-export, import, continue-import.
mirror-clones Reviewed collection of unpublished mirror clones: inspect, collect, inspect-root-removal, reconcile-root-removal, forget.
workspace Grouped workspace operations; see below.
version Print the build’s version.

--request-id is accepted only by create, recover, lease, run and setup, the operations the daemon replays.

The scalar commands share one flag set. Defaults that depend on the OS use Go’s user directories: the config directory for state and the cache directory for data (on Linux ~/.config and ~/.cache unless the XDG variables say otherwise; on macOS ~/Library/Application Support and ~/Library/Caches).

Flag Default Meaning
--state <config dir>/superbench/state Authoritative state, outside bench data.
--data <cache dir>/superbench/data Mirrors and checkouts.
--socket (none) Local benchd Unix socket; operation output uses the versioned API shape.
--request-id (none) Stable ID for replaying an accepted service request.
--repo (none) Git remote URL or absolute path.
--branch bench/<key> Task branch.
--base main Base branch.
--holder (none) Lease holder.
--token $BENCH_LEASE_TOKEN Lease token; prefer the environment variable.
--cgroup-root /sys/fs/cgroup/superbench Delegated Linux cgroup-v2 root for fenced execution.
--checkpoint true Checkpoint and release a successful supervised command.
--admin false Local operator: stop a supervised execution without its holder token.
--offline false Offline frozen dependency setup.
--mirror-timeout 2m0s Deadline for mirror clone, validation and fetch; the socket uses the daemon’s setting.
--quota-helper /usr/local/libexec/bench-quota Fixed-policy quota helper.
--quota-policy (none) Policy override for direct root testing and administration.
--min-data-free 67108864 Minimum free bytes on the data filesystem.
--min-state-free 1048576 Minimum free bytes on the state filesystem.
--max-log-bytes 1048576 Maximum captured output bytes per command.
--max-logs-bytes 67108864 Maximum retained and reserved run-log bytes.
--max-log-files 4096 Maximum retained run logs before admission stops.
--archive-grace 168h0m0s Local archive retention before reviewed reap; zero explicitly waives it.
--plan (none) Private reviewed administrative plan JSON.
--approve (none) Exact Digest of the reviewed plan.
--limit 100 History and collection result limit.
--after-key (none) Archive sweep cursor from the previous report’s Next field.
--older-than 168h0m0s Minimum time since release and log seal.
--metadata-older-than 720h0m0s Minimum time since prior log collection.
--max-collect-bytes 67108864 Maximum log bytes per automatic collection cycle.
--enable-automatic false Approve future automatic collections under the reviewed policy.
--acknowledge-stopped-writers false Operator confirms legacy log writers were stopped.

bench workspace OP [flags] [key] runs grouped operations. --socket selects the v2 API on the daemon; without it, the command uses local state. The client never retries on its own or falls back to v1.

Operations: create, recover, lease, setup, run, checkpoint, release, stop, stop_admin, archive, status, host_status, plan-reap, reap, and the reviewed local procedures inspect-history, reconcile-history, inspect-initialization, claim-initialization, continue-initialization, inspect-transfer, begin-transfer, continue-transfer, inspect-missing-transfer, begin-missing-transfer, continue-missing-transfer, inspect-root-removal and reconcile-root-removal.

Flag Meaning
--repositories File containing the canonical repositories JSON array.
--checkpoint-repository Logical checkpoint coordinator member.
--source File containing the exact recovery source JSON object.
--repository-name Selected member; omitted, run uses the root and setup uses all members.
--holder Workspace-wide lease holder.
--token Holder token; ordinary operations accept BENCH_LEASE_TOKEN.
--request-id Reuse this growth request ID after an interrupted reply.
--socket benchd Unix socket; uses v2 only.
--initialize Warm initialization is mandatory (default true).
--checkpoint Checkpoint and release a successful payload (default true).
--quota-bytes One total workspace budget, bounded by host policy.
--offline Offline frozen setup.
--archive-grace Local archive grace; zero explicitly waives retention (default 168h0m0s).
--plan Concrete reviewed local administration manifest file.
--approve Exact reviewed plan Digest.
--repair-id Explicit local initialization repair identity.
--rerun-once Review uncertain once hooks for these comma-separated members.
--transfer-id Explicit reviewed local transfer identity.
--target Fresh destination key for reviewed local transfer.
--disposition-id Fresh identity for explicit current empty-directory removal.
--cgroup-root Delegated local cgroup root (default /sys/fs/cgroup/superbench).
--mirror-timeout Local managed git deadline (default 2m0s).
--state, --data Local state and data, with the same defaults as above.