# bench CLI

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

## Bench lifecycle

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

## Local administration

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.

## Flags

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

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