Administration from the command line#

The viewer is where auditors and reviewers work: runs, verify, cases and reviews, evidence packs and the pack library, holds, redaction requests, replay, fork and regression suites. The acts below are done with the bitexact command instead. Each is there on purpose, and the reason is almost always the same: the act needs a secret, or runs a service, that has no business on the host serving a browser.

Needs a key the viewer must never hold#

Act	Command	Why not in the browser
Create the recorder key	`bitexact keygen`, `bitexact recorder-key`	The private key is generated where it will sign, or inside an HSM or KMS; it never crosses a web request.
Sign an export or an evidence pack	`bitexact export --sign`, `bitexact evidence-pack --sign`	The viewer exports unsigned bundles; a signature binds an identity, and that key belongs with the operator who vouches for it.
Sign attestation receipts	`bitexact receipts RUN --key --org`; `bitexact verify-receipts` checks them	Each receipt is signed; the receipt key stays with the operator (see Attestation receipts in the integrations guide).
Set what the evidence keeps of each field	`bitexact capture` (`policy show`, `test`, `keygen`)	The capture policy is a file on the host and the capture key must be kept apart from the evidence; the viewer shows the policy in force, read-only, under Settings › Capture policy.
Test a value against a hash-only field	`bitexact verify RUN --open 4:on_behalf_of --candidate-file FILE`, `bitexact verify RUN --open-withheld 9 --candidate-file FILE` (a step and a field path, or a gap's step; with `--by`)	It needs the capture key, which never crosses a web request; every test is recorded on the run's custody chain.
Define custom roles	`bitexact roles`	Every role event is signed with the recorder key, so an unsigned grant cannot pass as one. The viewer shows the roles, read-only.
Run the PKI	`bitexact pki` (`init`, `issue`, `revoke`, `crl`)	The CA's private key signs every host's identity.
Sign the transparency log	`bitexact log checkpoint`, `bitexact log backfill`	Signed with the recorder key; witnesses cosign.
Anchor run heads	`bitexact anchor`	Signs, and talks to your WORM store or time-stamping authority.

Runs a service, not a page#

Act	Command
The recording proxy	`bitexact serve`
The MCP relay, recording every `tools/call` between an MCP client and server	`bitexact mcp-proxy` (wrapping a stdio server, or `--listen` for Streamable HTTP)
A host collector	`bitexact collector`
The recorder	`bitexact recorder` (with `--health-port` for probes and metrics)
A witness, run by a third party	`bitexact witness`
The viewer itself	`bitexact view`

Changes the store wholesale#

Act	Command	Why
Retention, archiving and purge	`bitexact retention`, `bitexact archive`, `bitexact purge`	They act on many runs at once on a schedule; they belong in a reviewed job, not a button. Purge refuses held runs, and leaves a purge record signed with the recorder key so the transparency log reads each run as purged, not lost.
What an archived run carries	`bitexact archive`	Beside each run's bundle, `<run>.sidecars.json` holds its custody trail, failure markers and other sidecars, and under `governance.roles` the whole ledger of every custom role its custody entries name. Each custody entry names the role-ledger head in force when it was written (`role_head`, see identity-access), and the role ledgers are global, not dropped with the month - but they can be redefined, damaged or lost, and an archive kept for decades must resolve that head on its own. The ledger is carried whole, as the store holds it at archive time: it is append-only, so it contains every head the custody names. A role ledger the store holds but cannot read fails that run's archive, so nothing is dropped. Built-in roles have no ledger and carry the marker `built-in`.
Move between backends	`bitexact db-transfer`	A migration, run once, with the store quiet.
Repair and reindex	`bitexact repair`, `bitexact reindex`	Recovery after a crash or a restore - see the restore drill under Backup and restore in the deployment guide.
Seal a proxy-recorded run	`bitexact seal RUN`	The operator who knows a run is finished says so.

| Change a workflow's definition | bitexact workflow create, register-version, promote, set-retention, set-records-regime, deprecate | A workflow's versions, retention, records regime and withdrawal are configuration, reviewed like code. The viewer shows them, read-only. | | Audit the transparency log | bitexact log status, log audit, log heads, log consistency | Reads the whole log; an expired license still runs them. |

Belongs in CI#

bitexact lint (the determinism linter), bitexact suite run and bitexact regress (the regression gate), bitexact drift, bitexact fork-matrix, bitexact strict (fail on any capture gap) and bitexact coverage report --expected are made to fail a build. bitexact qualify measures a model configuration's determinism before it is relied on. The viewer shows their results; the pipeline runs them.

Setup and connections#

bitexact quickstart and bitexact seed (a real sample run) start a new deployment. bitexact events check validates the event delivery configuration, bitexact events test sends a test event to each destination, and bitexact events status, list and retry show and requeue what did not arrive (Event delivery).

Also in the viewer#

These read or act on single runs, and the viewer does the same for anyone whose role allows it: bitexact list, show, verify, verify-report, export, evidence-pack, provenance-bundle, otel-export, case, forks, hold, release-hold, and redact and redaction (erasure under dual control).

License and health#

bitexact license shows the license and whether this deployment's recorder key is one it names; bitexact version names the release for support. bitexact health reports integrity, capacity and every expiry on the calendar - see Ops health. The viewer's Settings show the same license and health.

Settings in the viewer#

Settings is one short section per concern, each at its own address (#settings/health, #settings/license, and so on; #settings alone opens Health). A desktop lists the sections down the left; a phone picks one from a list at the top.

Health: the store's status, five counts (runs failing verification, runs rolled back behind an anchor, interrupted writes, recording failures, unconfirmed streamed responses), the alerts, capacity, and the health command to run in a monitor.
License: who holds it, when it expires and how many days are left, what it grants in one line (the list opens under it), and where to renew. Then the environment and the installed version.
Keys: the same recorder-keys table the Trust page shows, each key with where it comes from (the evidence, this inspector, the license), and the bundle-signing key, which the viewer never holds.
Retention: the legal holds in force (a link to them on Runs), and for a role that may see it, a preview of what a purge would take now. The purge itself stays bitexact purge on the host.
Access: on a deployment with no authentication, a warning first (red on prod). Then who is signed in and their scope, and one table of every role against every action, as the server allows them; custom roles show where each came from. Roles are defined with bitexact roles on the host.
Access log (for a role that administers the viewer): who viewed or listed evidence, narrowed by who, action and run.
Command line: what is done on the host instead, and why, as commands to copy in this deployment's form.
This browser: the theme, and the way back to Get started.

Every command is in the CLI reference.