Command reference#
Generated from bitexact --help by tools/gen_reference.py; do not edit by hand.
The entitlement a command requires is listed in the CLI table at https://bitexact.dev/guide.html#cli.
Without a valid license only bitexact capture keygen, bitexact keygen, bitexact license, bitexact pki, bitexact recorder-key, bitexact version and bitexact witness answer. bitexact collector, bitexact mcp-proxy, bitexact recorder and bitexact serve start in any license state and check the license on each call: they pass the agents' traffic through, or declare a gap, rather than record.
usage: bitexact [-h]
{list,show,export,provenance-bundle,evidence-pack,workflow,drift,health,events,coverage,case,suite,redaction,retention,cost,keygen,recorder-key,license,version,view,repair,redact,reindex,db-grant-viewer,archive,db-transfer,seed,quickstart,seal,regress,fork-matrix,fork-matrix-compare,forks,purge,hold,release-hold,verify,verify-report,otel-export,receipts,verify-receipts,qualify,serve,mcp-proxy,pki,recorder,log,capture,witness,collector,lint,roles,strict,anchor} ...
BitExact flight recorder
positional arguments:
{list,show,export,provenance-bundle,evidence-pack,workflow,drift,health,events,coverage,case,suite,redaction,retention,cost,keygen,recorder-key,license,version,view,repair,redact,reindex,db-grant-viewer,archive,db-transfer,seed,quickstart,seal,regress,fork-matrix,fork-matrix-compare,forks,purge,hold,release-hold,verify,verify-report,otel-export,receipts,verify-receipts,qualify,serve,mcp-proxy,pki,recorder,log,capture,witness,collector,lint,roles,strict,anchor}
list list recorded runs
show show a run's verified steps
export export a verified run bundle
provenance-bundle package a run and its descendant forks/matrix as a
verifiable BagIt bag
evidence-pack assemble a workpaper-shaped, independently-verifiable
evidence pack for a run
workflow governance acts on a workflow's tamper-evident ledger
(recorded, never enforced)
drift report composition drift for a workflow (a CI pre-
flight to regress)
health store health for ops: verify/seal/anchor/recording
alerts + capacity (exit 2 on critical - a monitor
gate)
events event delivery: check the configuration, the outbox
and its dead letters, retry and test delivery,
Standard Webhooks secrets, and checking a delivery as
a receiver would
coverage capture-coverage: the corpus report of recorded
surfaces and capture-health (honest - never a
completeness measure), and the declared capture
sources
case an investigation case: pin runs, record
notes/assignees/findings on a tamper-evident ledger
(recorded, never enforced)
suite regression suites: save a corpus+recipe, run it as a
CI gate, compare two implementations on the same roots
redaction dual-control (two-person) redaction lifecycle:
request, approve (by a different principal), reject,
status
retention per-workflow retention report: committed deadlines vs
the declared schedule and legal holds
cost token usage per run, workflow, principal and agent,
priced from your own pricing table (derived, never
evidence)
keygen generate a hybrid signing key: ed25519 and its post-
quantum (ML-DSA) half
recorder-key print the public half of the configured recorder key
license show offline license status and standing; request and
install the 90-day renewal
version print the installed version
view browse, verify and fork recorded runs
repair quarantine a torn manifest tail and write journaled
entries a crash left into the chain
redact redact committed fields in the stored manifest
reindex rebuild index.db from manifests
db-grant-viewer let a PostgreSQL role read the store and write only
the inspector's operational records - never a chain -
so a viewer connected as it cannot append evidence
however it is driven. Run with the recorder's
BITEXACT_DATABASE_URL
archive export runs past the hot window to the archive and
drop them
db-transfer copy this install's evidence into a PostgreSQL
database
seed record a real, offline sample run so a fresh install
is never empty
quickstart print a copy-paste first-run on-ramp
seal close a proxy-recorded run with a run_end seal
regress regress recorded runs against changed code (nonzero
exit on proven divergence - a CI gate)
fork-matrix N live forks from a step; aggregate outcomes
fork-matrix-compare
set two fork-matrix reports at one fork point side by
side
forks print the fork provenance tree
purge archive or delete runs older than a cutoff
hold place a legal hold so purge refuses a run
release-hold release a legal hold, making a run purgeable
verify verify a run's chain
verify-report verify a signed regress-suite or qualification report
otel-export export a verified run as OTel GenAI spans (OTLP/JSON)
receipts export a verified run's model calls as signed
attestation receipts (IETF draft)
verify-receipts verify attestation receipts against a pinned key
qualify measure a model config's determinism
serve run the recording proxy
mcp-proxy relay an MCP server, recording every tools/call
pki create a CA and issue recorder and host certificates
recorder run the recorder service for host collectors
log the transparency log of every run head the recorder
signed: checkpoint, witness, audit
capture the capture policy: what the evidence keeps of each
field - scrubbed, hash-only or kept
witness cosign transparency-log checkpoints that extend the
last one cosigned (run by an independent party)
collector run this host's collector for the recorder
lint flag nondeterminism replay cannot capture
roles define custom roles and bind your IdP's groups to them
strict structural completeness checks for a run (a CI gate)
anchor externally anchor a run's head (WORM / RFC 3161) and
detect rollback
options:
-h, --help show this help message and exit
exit codes (each command's --help lists its own):
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
3 verified, with declared capture gaps - an intact record of an
incomplete capturebitexact anchor#
usage: bitexact anchor [-h] {export,timestamp,verify} ...
positional arguments:
{export,timestamp,verify}
export write a recorder-signed WORM anchor of the head
timestamp obtain an RFC 3161 timestamp of the head
verify verify anchors against the current store; rollback
below an anchor fails loud
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact anchor export#
usage: bitexact anchor export [-h] [--key KEY] [-o OUTPUT] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--key KEY path to the recorder ed25519 key file
-o, --output OUTPUT
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact anchor timestamp#
usage: bitexact anchor timestamp [-h] --tsa TSA [--nonce NONCE] [-o OUTPUT]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--tsa TSA RFC 3161 TSA URL (customer-configured); only the head
imprint is sent
--nonce NONCE
-o, --output OUTPUT
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact anchor verify#
usage: bitexact anchor verify [-h] [--anchor ANCHOR]
[--expect-recorder-key HEX]
[--expect-tsa EXPECT_TSA]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--anchor ANCHOR an anchor JSON file (else the run's sidecar)
--expect-recorder-key HEX
pin this recorder public key in place of the license's
recorder_keys: the run's checkpoints and every worm
anchor must be signed by it
--expect-tsa EXPECT_TSA
require rfc3161 tokens from this TSA certificate
(PEM/DER file)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact archive#
usage: bitexact archive [-h] --to TO [--keep-months KEEP_MONTHS]
[--before YYYY-MM] [--no-drop]
options:
-h, --help show this help message and exit
--to TO archive directory - point it at immutable (WORM /
object-lock) storage; the bundles written here are the
long-term evidence
--keep-months KEEP_MONTHS
months to keep queryable (defaults to
$BITEXACT_HOT_MONTHS)
--before YYYY-MM archive everything before this month instead of using
the hot window - for a deliberate one-off rather than
the routine sweep
--no-drop write the archive but keep the runs - a dry run for
the first time you do this against real evidence
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when a run failed to archive or a month could not be droppedbitexact capture#
usage: bitexact capture [-h] COMMAND ...
positional arguments:
COMMAND
policy show the policy in force, or check one
test what the policy in force scrubs from a text
keygen write a new capture key, owner-only
journal the bytes of a stream journal a failed finalization left behind,
opened with this host's key ($BITEXACT_HOST_KEY) - only the host
that sealed it can
backfill file one dual-control redaction request for every field of a
recorded run the policy in force would not have kept; history is
never rewritten
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture backfill#
usage: bitexact capture backfill [-h] --run RUN [--by BY] [--role ROLE]
options:
-h, --help show this help message and exit
--run RUN the run to backfill
--by BY the principal requesting (default: OS user)
--role ROLE the principal's role (recorded in custody)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture journal#
usage: bitexact capture journal [-h] [-o OUTPUT] file
positional arguments:
file
options:
-h, --help show this help message and exit
-o, --output OUTPUT write them to a new file, owner-only
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture keygen#
usage: bitexact capture keygen [-h] -o OUTPUT
options:
-h, --help show this help message and exit
-o, --output OUTPUT
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture policy#
usage: bitexact capture policy [-h] COMMAND ...
positional arguments:
COMMAND
show the policy in force, its digest and key
check whether a policy file is usable
digest a policy file's digest, as runs name it
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture policy check#
usage: bitexact capture policy check [-h] file
positional arguments:
file
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture policy digest#
usage: bitexact capture policy digest [-h] file
positional arguments:
file
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture policy show#
usage: bitexact capture policy show [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact capture test#
usage: bitexact capture test [-h] [--file FILE] [text]
positional arguments:
text the text to scrub
options:
-h, --help show this help message and exit
--file FILE read the text from FILE instead
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact case#
usage: bitexact case [-h] [--by BY] [--title TITLE]
[--kind {incident,exam-sample,regress-suite,inquiry}]
[--description DESCRIPTION] [--run RUN] [--step STEP]
[--reason REASON] [--assignee ASSIGNEE] [--text TEXT]
[--disposition {no-issue,issue,escalated}]
[--status {open,reviewing,closed}] [--allow-missing]
{create,pin,unpin,assign,unassign,note,finding,status,show,verify,list}
[case_id]
positional arguments:
{create,pin,unpin,assign,unassign,note,finding,status,show,verify,list}
case_id the case id (omitted only for `list`)
options:
-h, --help show this help message and exit
--by BY the principal performing the act (default: OS user)
--title TITLE create: the case title
--kind {incident,exam-sample,regress-suite,inquiry}
create: the kind of case
--description DESCRIPTION
--run RUN pin/unpin: the run id; note/finding: the pinned run it
is about (a finding about a whole run is its sign-off)
--step STEP note/finding: the step of --run it is about
--reason REASON pin/unpin: why
--assignee ASSIGNEE assign/unassign: the person
--text TEXT note/finding: the text
--disposition {no-issue,issue,escalated}
finding: the finding's disposition
--status {open,reviewing,closed}
status: the case's new status
--allow-missing pin: accept a run this store does not hold (an
external or archived run)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds the ledger does not verifybitexact collector#
usage: bitexact collector [-h] --spool SPOOL --recorder HOST:PORT
[--tls-cert TLS_CERT] [--tls-key TLS_KEY]
[--tls-ca TLS_CA] [--intake-port INTAKE_PORT]
[--intake-host HOST] [--intake-exposed]
[--max-spool-bytes MAX_SPOOL_BYTES]
[--intake-secret-file FILE]
[--drain-seconds DRAIN_S] [--insecure-loopback]
options:
-h, --help show this help message and exit
--spool SPOOL directory for the encrypted spool, host key and intake
secret
--recorder HOST:PORT
--tls-cert TLS_CERT this host's client certificate
--tls-key TLS_KEY its private key
--tls-ca TLS_CA the CA that issued the recorder's certificate
--intake-port INTAKE_PORT
--intake-host HOST the address the intake listens on (default 127.0.0.1).
Another address is for a collector in a container,
whose loopback agents outside it cannot reach: publish
the port to the host's loopback only, and say so with
--intake-exposed
--intake-exposed the --intake-host address is a container's, its port
published to the host's loopback alone. Without it a
non-loopback intake refuses to start
--max-spool-bytes MAX_SPOOL_BYTES
--intake-secret-file FILE
the host secret agents authenticate with, placed by
you where agents running as other users are granted
read access (at least 32 characters); default: created
owner-only in the spool
--drain-seconds DRAIN_S
on SIGTERM, keep forwarding for up to this long until
the spool is empty (default 30)
--insecure-loopback development only: plaintext to a loopback recorder
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact cost#
usage: bitexact cost [-h] [--run RUN] [--version COST_VERSION]
[--environment COST_ENVIRONMENT] [--json]
[workflow]
positional arguments:
workflow restrict to a workflow (else every recorded run)
options:
-h, --help show this help message and exit
--run RUN report one run instead
--version COST_VERSION
restrict the workflow to this version (needs the
workflow)
--environment COST_ENVIRONMENT
restrict to this environment, with or without a
workflow
--json print the report as JSON
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact coverage#
usage: bitexact coverage [-h] COMMAND ...
positional arguments:
COMMAND
report the corpus report: recorded surfaces, consistency, the capture
paths evidence came through and capture-health, read from the
manifests; nonzero exit when degraded
expect the declared capture sources, on a signed, hash-chained ledger:
add, remove, reject, withdraw, undeclared-alerts, list, import,
verify
sources the scorecard: whether evidence still arrives from every
declared source, read from the run index; nonzero exit unless
every one is live
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect#
usage: bitexact coverage expect [-h] ACTION ...
positional arguments:
ACTION
add declare a source, or replace the expectation of that id
remove remove an expectation; the removal and its reason stay
on the ledger
reject reject the pending requests to remove a critical
expectation, as a principal who did not request it
withdraw withdraw your own pending request to remove a critical
expectation
undeclared-alerts whether a source that writes evidence and no
expectation declares raises an alert; the change and
its reason stay on the ledger
list the declared expectations, the removed ones, and
whether undeclared sources alert
import apply JSON lines, each {"op": "expect", ...} or {"op":
"remove", "id", "reason"}; every line is checked before
any is written
verify re-walk the expectations ledger's chain and check every
signature; exit 2 when either fails
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect add#
usage: bitexact coverage expect add [-h] [--workflow MATCH_WORKFLOW]
[--environment MATCH_ENVIRONMENT]
[--agent-id MATCH_AGENT_ID]
[--path MATCH_PATH] [--host MATCH_HOST]
[--paths PATH[,PATH...]]
--max-silence DURATION
[--heartbeat DURATION]
[--severity {info,warning,critical}]
[--reason REASON] [--by BY]
ID
positional arguments:
ID the expectation's id
options:
-h, --help show this help message and exit
--workflow MATCH_WORKFLOW
match sources whose workflow is this (an unnamed part
matches any)
--environment MATCH_ENVIRONMENT
match sources whose environment is this (an unnamed
part matches any)
--agent-id MATCH_AGENT_ID
match sources whose agent_id is this (an unnamed part
matches any)
--path MATCH_PATH match sources whose path is this (an unnamed part
matches any)
--host MATCH_HOST match sources whose host is this (an unnamed part
matches any)
--paths PATH[,PATH...]
the capture paths expected to carry evidence, comma-
separated (proxy, relay:sdk-ts, ...)
--max-silence DURATION
how long the source may go without evidence, ISO-8601
(PT2H, P1DT30M)
--heartbeat DURATION how long its heartbeat may go unheard, ISO-8601
--severity {info,warning,critical}
the severity of its alert (default warning)
--reason REASON why the source is declared
--by BY the principal making the change, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect import#
usage: bitexact coverage expect import [-h] [--by BY] FILE
positional arguments:
FILE the JSON-lines file
options:
-h, --help show this help message and exit
--by BY the principal for a line that names none, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect list#
usage: bitexact coverage expect list [-h] [--json]
options:
-h, --help show this help message and exit
--json print the inventory as JSON
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect reject#
usage: bitexact coverage expect reject [-h] --reason REASON [--by BY] ID
positional arguments:
ID the expectation's id
options:
-h, --help show this help message and exit
--reason REASON why, recorded on the ledger beside the request it answers
--by BY the principal making the change, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect remove#
usage: bitexact coverage expect remove [-h] --reason REASON [--by BY] ID
positional arguments:
ID the expectation's id
options:
-h, --help show this help message and exit
--reason REASON why it is removed: removing an expectation is how a silent
source would be hidden
--by BY the principal making the change, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect undeclared-alerts#
usage: bitexact coverage expect undeclared-alerts [-h] --reason REASON
[--severity {info,warning,critical}]
[--by BY]
{on,off}
positional arguments:
{on,off} on to alert per undeclared source, off to stop
options:
-h, --help show this help message and exit
--reason REASON why, recorded on the ledger: turning the alerts off is
how a new source would go unnoticed
--severity {info,warning,critical}
the severity of each alert, with on (default warning)
--by BY the principal making the change, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect verify#
usage: bitexact coverage expect verify [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage expect withdraw#
usage: bitexact coverage expect withdraw [-h] --reason REASON [--by BY] ID
positional arguments:
ID the expectation's id
options:
-h, --help show this help message and exit
--reason REASON why, recorded on the ledger beside the request it answers
--by BY the principal making the change, recorded (default: OS
user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage report#
usage: bitexact coverage report [-h] [--version COV_VERSION]
[--environment COV_ENVIRONMENT]
[--expected FILE]
[workflow]
positional arguments:
workflow restrict to a workflow (else every recorded run)
options:
-h, --help show this help message and exit
--version COV_VERSION
restrict the workflow to this version (needs the
workflow)
--environment COV_ENVIRONMENT
restrict to this environment, with or without a
workflow
--expected FILE the executions that should have evidence, one run id
per line (from your orchestrator): reports coverage
and names every one that left none; nonzero exit if
any
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact coverage sources#
usage: bitexact coverage sources [-h] [--json] [--workflow WORKFLOW]
[--environment ENVIRONMENT] [--rebuild]
options:
-h, --help show this help message and exit
--json print the result as JSON
--workflow WORKFLOW only this workflow's expectations and sources
--environment ENVIRONMENT
only this environment's expectations and sources
--rebuild recompute the source index from the manifests and name
every source whose indexed row differed; nonzero exit
if any did
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification);
2 when `expect verify` or `sources` finds the expectations ledger's chain
or a signature does not verifybitexact db-grant-viewer#
usage: bitexact db-grant-viewer [-h] role
positional arguments:
role the database role the viewer connects as (create it first)
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact db-transfer#
usage: bitexact db-transfer [-h] [--to TO] [--no-verify] [-v]
options:
-h, --help show this help message and exit
--to TO target DSN (defaults to $BITEXACT_DATABASE_URL)
--no-verify skip re-walking each migrated run's chain in the target
(faster, and worth strictly less)
-v, --verbose name each run as it moves
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when a run failed to transferbitexact drift#
usage: bitexact drift [-h] workflow
positional arguments:
workflow
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the gate does not pass (a finding, not a failed verification)bitexact events#
usage: bitexact events [-h] COMMAND ...
positional arguments:
COMMAND
check validate the events configuration and print its
destinations and secret fingerprints; exit 1 on an error
status the outbox: rows by state, the oldest pending, dead
letters by destination; exit 2 on events dropped or a
configuration that does not load
list delivery rows, newest first
retry requeue dead letters: one event's, or --all-dead; each
retry is written to the access log with the principal
test enqueue an events.test event and run one delivery round
for it, printing the outcome
secret write a new whsec_ webhook secret, owner-only; prints its
fingerprint, never the secret
run deliver the event outbox in the foreground until
interrupted, reconciling the last 24 hours first
deliver run one delivery round and exit, for cron
reconcile re-derive the events of the facts recorded since an
instant and enqueue the ones a crash lost; an event
already in the outbox is kept once
verify-delivery check a captured Standard Webhooks delivery: its
signature, timestamp and body
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events check#
usage: bitexact events check [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events deliver#
usage: bitexact events deliver [-h] --once
options:
-h, --help show this help message and exit
--once one round (the only mode; `events run` keeps delivering)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events list#
usage: bitexact events list [-h]
[--state {dead,pending,awaiting_ack,delivered}]
[--limit N]
options:
-h, --help show this help message and exit
--state {dead,pending,awaiting_ack,delivered}
only rows in this state (default every state)
--limit N print at most N rows (default 100)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events reconcile#
usage: bitexact events reconcile [-h] --since ISO
options:
-h, --help show this help message and exit
--since ISO the start of the window, an ISO-8601 instant (naive is UTC)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events retry#
usage: bitexact events retry [-h] [--destination N] [--by BY]
(--all-dead | EVENT_ID)
positional arguments:
EVENT_ID the event whose dead letters to requeue
options:
-h, --help show this help message and exit
--all-dead requeue every dead letter
--destination N only the dead letters of this destination
--by BY the principal requeueing, written to the access log
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events run#
usage: bitexact events run [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events secret#
usage: bitexact events secret [-h] --out FILE
options:
-h, --help show this help message and exit
--out FILE the file to create (an existing one is refused)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events status#
usage: bitexact events status [-h] [--json]
options:
-h, --help show this help message and exit
--json print the status as JSON
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events test#
usage: bitexact events test [-h] [--destination N] [--by BY]
options:
-h, --help show this help message and exit
--destination N only this destination (default each one)
--by BY the principal sending the test, named in it
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact events verify-delivery#
usage: bitexact events verify-delivery [-h] --secret-file F --headers H
--body B [--tolerance SECONDS]
options:
-h, --help show this help message and exit
--secret-file F a file holding a whsec_ secret or a whpk_ public key
(repeatable, for a rotation)
--headers H a JSON file of the delivery's headers, name to value
--body B a file of the body bytes as received
--tolerance SECONDS how far webhook-timestamp may be from this host's clock
(default 300)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `status` finds events dropped at max_pending or a configuration
that does not load; 1 also when `check` finds the configuration invalid,
`retry` matches no dead letter, `test` is not accepted, `verify-delivery`
rejects the delivery, or `run` finds no configuration, or `deliver` none
that loads or a round that fails, or `reconcile` finds no configuration or
a run or ledger it cannot readbitexact evidence-pack#
usage: bitexact evidence-pack [-h] [--workflow WORKFLOW] [--case CASE]
[--runs RUNS] [--environment ENVIRONMENT]
[--workflow-version WORKFLOW_VERSION]
[--since ISO8601] [--until ISO8601]
[--subject KEY] [--principal PRINCIPAL]
[--agent AGENT_ID] [--on-behalf-of PARTY]
[--interaction {interactive,autonomous}]
[--save NAME] [--pack NAME] [--list-packs]
[-o OUTPUT] [--sign] [--key KEY]
[--preparer PREPARER] [--verifier VERIFIER]
[--no-view] [--by BY] [--force]
[run_id]
positional arguments:
run_id a run, or --workflow for a workflow-scoped pack
options:
-h, --help show this help message and exit
--workflow WORKFLOW pack every recorded run of a workflow plus its
governance ledger and an inventory workpaper
--case CASE pack every pinned run of a case plus its chain-of-
custody ledger and a case workpaper
--runs RUNS comma-separated run ids to pack as one selection (an
auditor's list); combines with the filters below,
which then narrow it
--environment ENVIRONMENT
narrow the selection to one environment
--workflow-version WORKFLOW_VERSION
narrow the selection to one workflow version
--since ISO8601 only runs started at or after this instant (inclusive)
--until ISO8601 only runs started before this instant (exclusive, so
adjacent windows tile a period without counting a run
twice)
--subject KEY only the decisions about this subject: the business
key (case, application, customer id) a run committed
as its workflow_instance
--principal PRINCIPAL
only the runs whose agent acted as this identity, as
the run's identity committed it
--agent AGENT_ID only the runs of this agent, as the run's identity
committed its agent_id
--on-behalf-of PARTY only the runs done on behalf of this party, as the
run's current identity states it
--interaction {interactive,autonomous}
only the runs with a person in the session
(interactive) or none (autonomous)
--save NAME also save this selection to the pack library under
NAME, to issue again with --pack
--pack NAME issue a saved pack: its selection, resolved against
the store now
--list-packs list the saved packs and exit
-o, --output OUTPUT pack directory (default <run>.evidence-pack)
--sign sign each run bundle and the graph attestation with
--key
--key KEY path to an ed25519 private key file
--preparer PREPARER preparer name/org for the workpaper cover (default:
the bound principal)
--verifier VERIFIER path to bitexact_verifier.py to vendor into the pack,
pinned by its own sha256 (for air-gapped auditors)
--no-view omit the reading view (data/view.html), for a relying
party that forbids opening HTML; the pack verifies
without it
--by BY the principal exporting, recorded on the custody chain
with role operator (default: OS user)
--force replace an existing bag directory whole (only a bag)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact export#
usage: bitexact export [-h] [-o OUTPUT] [--by BY] [--sign] [--key KEY]
[--redact-steps REDACT_STEPS]
[--format {json,dsse,jsonl}]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
-o, --output OUTPUT
--by BY the principal exporting, recorded on the custody chain
with role operator (default: OS user)
--sign sign the bundle with --key
--key KEY path to an ed25519 private key file
--redact-steps REDACT_STEPS
comma-separated step indices whose data and salt are
removed; the chain still verifies
--format {json,dsse,jsonl}
dsse wraps the bundle in a signed in-toto statement
(requires --sign); jsonl streams header + one entry
per line for GB-scale runs
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact fork-matrix#
usage: bitexact fork-matrix [-h] --at-step AT_STEP --n N --entry ENTRY
[--model MODEL] [--run-prefix RUN_PREFIX]
[--accept-scrubbed] [-o OUTPUT]
source_run
positional arguments:
source_run
options:
-h, --help show this help message and exit
--at-step AT_STEP step index or KIND:N (e.g. http_call:2)
--n N number of live forks to run
--entry ENTRY MODULE:FUNCTION taking the active run, returning the
fork's outcome
--model MODEL declared model dimension for this arm
--run-prefix RUN_PREFIX
prefix for the fork run ids
--accept-scrubbed serve the prefix's scrubbed values as scrubbed
(default: a fork past one is refused)
-o, --output OUTPUT also write the report to a path
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when a fork erroredbitexact fork-matrix-compare#
usage: bitexact fork-matrix-compare [-h] [--run RUN] [--a HASH] [--b HASH]
[--json]
[REPORT ...]
positional arguments:
REPORT two fork-matrix report files: arm a, then arm b
options:
-h, --help show this help message and exit
--run RUN read the reports from this source run's store
--a HASH report_hash of arm a, with --run
--b HASH report_hash of arm b, with --run
--json print the comparison as JSON
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the two reports cannot be compared: a report hash that does
not recompute, or a different source run or fork pointbitexact forks#
usage: bitexact forks [-h] [run_id]
positional arguments:
run_id scope the tree to this run's lineage (default: every root in the
store)
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact health#
usage: bitexact health [-h] [--json] [--cert PEM] [--crl PEM] [--warn-days N]
options:
-h, --help show this help message and exit
--json emit the raw health report as JSON
--cert PEM a certificate to check for expiry (repeatable): the
recorder's, each host's
--crl PEM a revocation list to check for expiry (repeatable); past it
the recorder refuses every host
--warn-days N warn this many days before a certificate, revocation list or
the license expires (default 30)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 on a critical status: a run that fails verification, or an anchor
rollbackbitexact hold#
usage: bitexact hold [-h] [--reason REASON] [--by BY] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--reason REASON required: the matter or ticket the hold is for (recorded in
the chained hold entry)
--by BY the principal performing this act, recorded in the chained
audit entry
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact keygen#
usage: bitexact keygen [-h] -o OUTPUT [--force]
[--suite {hybrid,ed25519,witness-ml-dsa-44}]
[--pq-alg {ML-DSA-65,ML-DSA-87}]
options:
-h, --help show this help message and exit
-o, --output OUTPUT where to write the ed25519 key; the post-quantum half,
its ML-DSA seed as 64 hex characters, goes to
<name>.pq.key
--force overwrite an existing key file
--suite {hybrid,ed25519,witness-ml-dsa-44}
hybrid (default); ed25519 alone - classical-only, not
resistant to a quantum forger; or witness-ml-dsa-44, a
witness key that cosigns with C2SP ML-DSA-44
cosignatures
--pq-alg {ML-DSA-65,ML-DSA-87}
the post-quantum parameter set (default
$BITEXACT_PQ_ALG, else ML-DSA-65). The key file holds
only the 32-byte seed, so the signer takes the set
from $BITEXACT_PQ_ALG too: set it to the same value
where the key signs
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact license#
usage: bitexact license [-h] {request,install,usage} ...
positional arguments:
{request,install,usage}
request write a renewal request, signed by the recorder key
and carrying a TPM quote, to send to BitExact
install install the renewed license BitExact sent back over
the license BITEXACT_LICENSE names
usage count the production agent identities seen recording
in the last 90 days, beside the licensed band
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact license install#
usage: bitexact license install [-h] file
positional arguments:
file the renewed license file
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact license request#
usage: bitexact license request [-h] --out OUT
options:
-h, --help show this help message and exit
--out OUT the file to write the request to
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact license usage#
usage: bitexact license usage [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact lint#
usage: bitexact lint [-h] [--format {text,json,sarif}] paths [paths ...]
positional arguments:
paths
options:
-h, --help show this help message and exit
--format {text,json,sarif}
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the gate does not pass (a finding, not a failed verification)bitexact list#
usage: bitexact list [-h] [--subject KEY] [--principal PRINCIPAL]
[--agent AGENT_ID] [--on-behalf-of PARTY]
[--interaction {interactive,autonomous}]
[--since ISO8601] [--until ISO8601]
options:
-h, --help show this help message and exit
--subject KEY the decisions about this subject: the business key a
run committed as its workflow_instance
--principal PRINCIPAL
the runs whose agent acted as this identity
--agent AGENT_ID the runs of this agent, as the run's identity
committed its agent_id
--on-behalf-of PARTY the runs done on behalf of this party, as the run's
current identity states it
--interaction {interactive,autonomous}
the runs with a person in the session (interactive) or
none (autonomous)
--since ISO8601 runs started at or after this instant
--until ISO8601 runs started before this instant
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact log#
usage: bitexact log [-h] COMMAND ...
positional arguments:
COMMAND
checkpoint sign the log's head and have the witnesses in
BITEXACT_LOG_WITNESSES cosign it
status the log's size and latest checkpoint
audit every run the log names that the store lost, and every signed
run checkpoint the log lacks; nonzero exit if any
backfill add the recorder-signed run checkpoints the log lacks
heads every head of a run the log holds, oldest first
tail the log from leaf START as JSON (from, leaves, left), for the
verifier's --log-tail: checks a bundle's head is its run's
latest logged head against a log checkpoint you hold
consistency prove today's log extends a checkpoint you kept
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log audit#
usage: bitexact log audit [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log backfill#
usage: bitexact log backfill [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log checkpoint#
usage: bitexact log checkpoint [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log consistency#
usage: bitexact log consistency [-h] [--log-key LOG_KEY] note
positional arguments:
note a checkpoint note saved earlier
options:
-h, --help show this help message and exit
--log-key LOG_KEY the log's public key (hex); default: the recorder key's
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log heads#
usage: bitexact log heads [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log status#
usage: bitexact log status [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact log tail#
usage: bitexact log tail [-h] [--size N] START
positional arguments:
START the first leaf of the tail (0-based)
options:
-h, --help show this help message and exit
--size N end the tail at the log's first N leaves, the size of the
checkpoint you hold (default: the whole log)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `audit` finds a logged run the store lost, a signed checkpoint the
log lacks or a leaf it cannot read, or `consistency` finds the log does
not extend the kept checkpoint; 1 also when `tail` names a range the log
does not holdbitexact mcp-proxy#
usage: bitexact mcp-proxy [-h] [--run-id RUN_ID] [--replay RUN]
[--listen PORT] [--upstream URL] [--host HOST]
[SERVER ...]
positional arguments:
SERVER stdio: the server's command line, after --
options:
-h, --help show this help message and exit
--run-id RUN_ID stdio: the run every tools/call is recorded into; without
it, the run each call names in
params._meta["bitexact/run_id"]
--replay RUN answer each tools/call from this recorded run
--listen PORT Streamable HTTP: the port clients connect to
--upstream URL Streamable HTTP: the server's base URL
--host HOST Streamable HTTP: the address to listen on
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the stdio MCP server exits nonzero, or a --replay diverged or
left a recorded tools/call unserved; 2 when the --replay run does not
verifybitexact otel-export#
usage: bitexact otel-export [-h] [-o OUTPUT] [--by BY] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
-o, --output OUTPUT
--by BY the principal exporting, recorded on the custody chain
with role operator (default: OS user)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact pki#
usage: bitexact pki [-h] {init,issue,revoke,crl} ...
positional arguments:
{init,issue,revoke,crl}
init create a certificate authority
issue issue a certificate for the recorder or a host
revoke revoke a host's certificate (rewrites ca.crl)
crl write or renew the revocation list (ca.crl)
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact pki crl#
usage: bitexact pki crl [-h] --dir DIR
options:
-h, --help show this help message and exit
--dir DIR
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact pki init#
usage: bitexact pki init [-h] --dir DIR [--name NAME]
options:
-h, --help show this help message and exit
--dir DIR
--name NAME
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact pki issue#
usage: bitexact pki issue [-h] --dir DIR [--dns DNS] [--ip IP]
[--spiffe SPIFFE] [--days DAYS]
NAME
positional arguments:
NAME
options:
-h, --help show this help message and exit
--dir DIR
--dns DNS a DNS name it serves (repeatable)
--ip IP an IP address it serves (repeatable)
--spiffe SPIFFE the workload's SPIFFE ID: the peer its events are recorded
under
--days DAYS
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact pki revoke#
usage: bitexact pki revoke [-h] --dir DIR NAME
positional arguments:
NAME
options:
-h, --help show this help message and exit
--dir DIR
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact provenance-bundle#
usage: bitexact provenance-bundle [-h] [-o OUTPUT] [--by BY] [--force]
[--sign] [--key KEY] [--no-view]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
-o, --output OUTPUT bag directory (default <run>.provenance-bag)
--by BY the principal exporting, recorded on the custody chain
with role operator (default: OS user)
--force replace an existing bag directory whole (only a bag)
--sign sign each run bundle and the graph attestation with
--key
--key KEY path to an ed25519 private key file
--no-view omit the reading view (data/view.html), for a relying
party that forbids opening HTML; the bag verifies
without it
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact purge#
usage: bitexact purge [-h] --older-than DAYS [--archive DIR] [--delete]
[--yes] [--dry-run]
options:
-h, --help show this help message and exit
--older-than DAYS cutoff in days by last entry timestamp
--archive DIR move the runs' files into DIR
--delete permanently delete (requires --yes)
--yes confirm permanent deletion
--dry-run
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact qualify#
usage: bitexact qualify [-h] [--base-url BASE_URL] [--wire {openai,anthropic}]
--model MODEL --prompt PROMPT [-n N]
[--temperature TEMPERATURE] [--seed SEED] [-o OUTPUT]
[--sign] [--key KEY]
options:
-h, --help show this help message and exit
--base-url BASE_URL
--wire {openai,anthropic}
--model MODEL
--prompt PROMPT
-n N
--temperature TEMPERATURE
--seed SEED
-o, --output OUTPUT
--sign sign the report with --key
--key KEY path to an ed25519 private key file
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when sampling aborted (the partial report is written)bitexact quickstart#
usage: bitexact quickstart [-h] [--host HOST] [--port PORT]
options:
-h, --help show this help message and exit
--host HOST
--port PORT
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact receipts#
usage: bitexact receipts [-h] --key KEY --org ORG [-o OUTPUT] [--by BY]
[--allow-gaps]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--key KEY path to the ed25519 private key that signs the receipts
--org ORG the organization the receipts are about
-o, --output OUTPUT
--by BY the principal exporting, recorded on the custody chain
with role operator (default: OS user)
--allow-gaps exit 0 even when a model call gets no receipt
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
3 verified, with declared capture gaps - an intact record of an
incomplete capture
3 when a model call gets no receipt, unless --allow-gapsbitexact recorder#
usage: bitexact recorder [-h] [--host HOST] [--port PORT]
[--tls-cert TLS_CERT] [--tls-key TLS_KEY]
[--tls-client-ca TLS_CLIENT_CA] [--tls-crl TLS_CRL]
[--insecure-loopback] [--health-port PORT]
[--health-host HEALTH_HOST]
options:
-h, --help show this help message and exit
--host HOST
--port PORT
--tls-cert TLS_CERT the recorder's TLS certificate
--tls-key TLS_KEY its private key
--tls-client-ca TLS_CLIENT_CA
the CA whose client certificates identify collectors
(required)
--tls-crl TLS_CRL the CA's revocation list (`bitexact pki crl`): a
revoked host is refused, even mid-session
--insecure-loopback development only: plaintext on loopback
--health-port PORT serve /livez, /readyz and /metrics over plain HTTP on
this port, for orchestrator probes and Prometheus
--health-host HEALTH_HOST
address the health port binds (default 0.0.0.0, so the
kubelet can reach it)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact recorder-key#
usage: bitexact recorder-key [-h] [--pq]
options:
-h, --help show this help message and exit
--pq print its post-quantum (ML-DSA) public key instead
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact redact#
usage: bitexact redact [-h] [--steps STEPS] [--fields FIELDS] [--by BY] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--steps STEPS comma-separated steps to redact entirely
--fields FIELDS comma-separated step:path selections, e.g.
3:request.text,3:response.text
--by BY the principal performing this act, recorded in the chained
audit entry
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact redaction#
usage: bitexact redaction [-h] [--by BY] [--role ROLE] [--steps STEPS]
[--fields FIELDS] [--reason REASON]
{request,approve,reject,status} run_id
positional arguments:
{request,approve,reject,status}
run_id
options:
-h, --help show this help message and exit
--by BY the principal performing the act (default: OS user)
--role ROLE the principal's role (recorded in custody; default
operator)
--steps STEPS request: comma-separated steps to redact
--fields FIELDS request: comma-separated STEP:PATH fields
--reason REASON request/reject: why (required for both)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact regress#
usage: bitexact regress [-h] [--workflow WORKFLOW] [--version REGRESS_VERSION]
[--environment REGRESS_ENVIRONMENT] --entry ENTRY
[--intended INTENDED] [--accept-scrubbed]
[--git-sha GIT_SHA] [--label LABEL] [--sign]
[--key KEY] [-o OUTPUT]
[run_ids ...]
positional arguments:
run_ids explicit run ids, or select by workflow below
options:
-h, --help show this help message and exit
--workflow WORKFLOW regress a whole workflow's corpus instead of explicit
run ids (verifiable version-drift)
--version REGRESS_VERSION
restrict --workflow to this workflow_version
--environment REGRESS_ENVIRONMENT
restrict --workflow to this environment
--entry ENTRY MODULE:FUNCTION taking the active run
--intended INTENDED KIND:PATH change declarations; flips confined to them
are intended, not divergence (repeatable)
--accept-scrubbed serve a value the capture policy scrubbed, as scrubbed
(default: the step is withheld)
--git-sha GIT_SHA code identity for the report
--label LABEL human label for the report
--sign sign the suite report with --key
--key KEY path to an ed25519 private key file
-o, --output OUTPUT
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the gate does not pass (a finding, not a failed verification)bitexact reindex#
usage: bitexact reindex [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact release-hold#
usage: bitexact release-hold [-h] [--reason REASON] [--by BY] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--reason REASON required: why the hold can end - the matter or ticket it
was for (recorded in the chained hold_release entry)
--by BY the principal performing this act, recorded in the chained
audit entry
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact repair#
usage: bitexact repair [-h] [--accept-truncation] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--accept-truncation accept and record missing steps that no torn line
explains
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact retention#
usage: bitexact retention [-h] [--version RET_VERSION]
[--environment RET_ENVIRONMENT]
[workflow]
positional arguments:
workflow restrict to a workflow (else every recorded run)
options:
-h, --help show this help message and exit
--version RET_VERSION
restrict the workflow to this version (needs the
workflow)
--environment RET_ENVIRONMENT
restrict to this environment, with or without a
workflow
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the gate does not pass (a finding, not a failed verification)bitexact roles#
usage: bitexact roles [-h] {define,remove,bind,unbind,list,verify} ...
positional arguments:
{define,remove,bind,unbind,list,verify}
define define or redefine a role
remove remove a role
bind bind an IdP group to a role
unbind revoke a group binding
list every custom role and its permissions
verify re-walk and authenticate every role chain
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles bind#
usage: bitexact roles bind [-h] [--by BY] group name
positional arguments:
group
name
options:
-h, --help show this help message and exit
--by BY who is making the change (recorded)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles define#
usage: bitexact roles define [-h] --allow ALLOW [--by BY] name
positional arguments:
name
options:
-h, --help show this help message and exit
--allow ALLOW comma-separated permissions the role grants
--by BY who is making the change (recorded)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles list#
usage: bitexact roles list [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles remove#
usage: bitexact roles remove [-h] [--by BY] name
positional arguments:
name
options:
-h, --help show this help message and exit
--by BY who is making the change (recorded)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles unbind#
usage: bitexact roles unbind [-h] [--by BY] group name
positional arguments:
group
name
options:
-h, --help show this help message and exit
--by BY who is making the change (recorded)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact roles verify#
usage: bitexact roles verify [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds a role chain that does not verifybitexact seal#
usage: bitexact seal [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact seed#
usage: bitexact seed [-h] [--clean]
options:
-h, --help show this help message and exit
--clean delete any prior sample run and re-seed
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact serve#
usage: bitexact serve [-h] [--host HOST] [--port PORT] [--tls-cert TLS_CERT]
[--tls-key TLS_KEY] [--tls-client-ca TLS_CLIENT_CA]
options:
-h, --help show this help message and exit
--host HOST
--port PORT
--tls-cert TLS_CERT TLS certificate for the listener
--tls-key TLS_KEY TLS private key
--tls-client-ca TLS_CLIENT_CA
require client certificates signed by this CA (mTLS)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact show#
usage: bitexact show [-h] [--causal] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--causal order a multi-agent run by what caused what (host-asserted)
rather than by chain position
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact strict#
usage: bitexact strict [-h] [--require-identity] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--require-identity also require an identity binding
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
1 also when the gate does not pass (a finding, not a failed verification)bitexact suite#
usage: bitexact suite [-h] [--entry ENTRY] [--runs [RUNS ...]]
[--workflow WORKFLOW] [--version SUITE_VERSION]
[--environment SUITE_ENVIRONMENT] [--intended INTENDED]
[--max-divergence MAX_DIVERGENCE] [--accept-scrubbed]
[--description DESCRIPTION] [--git-sha GIT_SHA]
[--label LABEL] [--entry-a ENTRY_A] [--entry-b ENTRY_B]
[--label-a LABEL_A] [--label-b LABEL_B]
{create,run,compare,show,list} [suite]
positional arguments:
{create,run,compare,show,list}
suite the suite name (omitted only for `list`)
options:
-h, --help show this help message and exit
--entry ENTRY create: MODULE:FUNCTION of the code under test
--runs [RUNS ...] create: explicit run ids for the corpus
--workflow WORKFLOW create: select the corpus by workflow instead
--version SUITE_VERSION
create: restrict --workflow to this version
--environment SUITE_ENVIRONMENT
create: restrict --workflow to this environment
--intended INTENDED create: KIND:PATH allow-listed change (repeatable)
--max-divergence MAX_DIVERGENCE
create: fraction of the corpus allowed to diverge
before the gate fails (default 0.0)
--accept-scrubbed create: serve values the capture policy scrubbed, as
scrubbed (default: such a run is withheld from the
gate)
--description DESCRIPTION
--git-sha GIT_SHA run: code identity for the result
--label LABEL run: human label for the result
--entry-a ENTRY_A compare: MODULE:FUNCTION of implementation A
--entry-b ENTRY_B compare: MODULE:FUNCTION of implementation B
--label-a LABEL_A
--label-b LABEL_B
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
1 also when the gate does not pass (a finding, not a failed verification)bitexact verify#
usage: bitexact verify [-h] [--provenance] [--expect-recorder-key HEX]
[--expect-recorder-pq-key HEX|FILE] [--trust-file FILE]
[--require-pq] [--allow-gaps CAUSES]
[--open STEP:PATH | --open-withheld STEP]
[--candidate-file FILE] [--by BY]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--provenance also cross-check the whole fork ancestry against the
source manifests
--expect-recorder-key HEX
pin this recorder public key in place of the license's
recorder_keys: every checkpoint must be signed by it
and a sealed run must carry one, or verification
FAILS. With --provenance every run in the fork lineage
must carry a head-covering checkpoint signed by it -
without it a fork's descent is only structural (the
source's public hash), forgeable by a store writer
--expect-recorder-pq-key HEX|FILE
the post-quantum (ML-DSA) half of the key --expect-
recorder-key pins: every checkpoint and worm anchor
that key signed must carry a post-quantum signature by
it, so a forger holding only the Ed25519 key fails
--trust-file FILE the open verifier's trust file, read the same way:
every checkpoint must be signed by one of its
recorder_keys, and an entry's pq_public_key demands
that post-quantum half on everything the key signed.
One Ed25519 key listed with two PQ keys allows a
rotation between them. In place of the license's
recorder_keys and of --expect-recorder-key
--require-pq fail a run any of whose checkpoints or worm anchors
carries no post-quantum signature (it pins no key: a
forger who recovers the Ed25519 key can add an ML-DSA
key of their own - pin it to refuse that)
--allow-gaps CAUSES exit 0 rather than 3 when every capture gap the run
declares has one of these causes (comma-separated) or
with 'all'; the gaps are still listed
--open STEP:PATH once the run verifies, test --candidate-file (the
value, as JSON) against this hash-only field with the
capture key: prints matches or does not match (exit
2). Recorded on the run's custody chain first -
testing a candidate is guessing one
--open-withheld STEP once the run verifies, test --candidate-file's exact
bytes against the content the gap at this step
withheld, with the capture key; recorded on the
custody chain like --open
--candidate-file FILE
the candidate --open or --open-withheld tests
--by BY with --open or --open-withheld, the principal testing
the candidate, recorded on the custody chain
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
3 verified, with declared capture gaps - an intact record of an
incomplete capture
3 unless --allow-gaps accepts every declared cause; with --open or --open-
withheld, 0 when the candidate matches and 2 when it does notbitexact verify-receipts#
usage: bitexact verify-receipts [-h] --expect-key EXPECT_KEY file
positional arguments:
file receipts, one JSON object per line
options:
-h, --help show this help message and exit
--expect-key EXPECT_KEY
the trusted ed25519 public key (base64url)
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact verify-report#
usage: bitexact verify-report [-h] [--expect-key EXPECT_KEY]
[--expect-pq-key HEX|FILE]
[--expect-kind {bitexact-regress-suite,bitexact-regress-report,bitexact-qualification}]
report
positional arguments:
report path to the signed report JSON
options:
-h, --help show this help message and exit
--expect-key EXPECT_KEY
require this ed25519 public key (hex)
--expect-pq-key HEX|FILE
require the report's post-quantum (ML-DSA) signature
to be by this key
--expect-kind {bitexact-regress-suite,bitexact-regress-report,bitexact-qualification}
require this kind of report, so a valid report of
another kind is not accepted in its place
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)bitexact version#
usage: bitexact version [-h]
options:
-h, --help show this help message and exit
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact view#
usage: bitexact view [-h] [--host HOST] [--port PORT] [--tls-cert TLS_CERT]
[--tls-key TLS_KEY]
options:
-h, --help show this help message and exit
--host HOST
--port PORT
--tls-cert TLS_CERT TLS certificate for the listener
--tls-key TLS_KEY TLS private key
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact witness#
usage: bitexact witness [-h] --name NAME --key KEY --state STATE
[--log ORIGIN=KEY[:PQKEY]] [--host HOST] [--port PORT]
[--tls-cert TLS_CERT] [--tls-key TLS_KEY]
options:
-h, --help show this help message and exit
--name NAME this witness's name, e.g. witness.auditor.example
--key KEY file holding this witness's private key, from
`bitexact keygen --suite ed25519` or `--suite witness-
ml-dsa-44` (post-quantum C2SP cosignatures)
--state STATE directory where the last cosigned head of each log is
kept
--log ORIGIN=KEY[:PQKEY]
a log to witness and its public key, and - for a
hybrid log - its post-quantum (ML-DSA) key after a
colon, which its notes must then be signed with too
(repeatable)
--host HOST
--port PORT
--tls-cert TLS_CERT serve HTTPS with this certificate
--tls-key TLS_KEY its private key
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reachedbitexact workflow#
usage: bitexact workflow [-h] [--by BY] [--owner OWNER]
[--description DESCRIPTION]
[--criticality {tier-1,tier-2,tier-3}]
[--version VERSION] [--code CODE]
[--policy-version POLICY_VERSION]
[--regress-suite REGRESS_SUITE] [--notes NOTES]
[--to TO] [--from FROM_ENV] [--gate GATE]
[--schedule SCHEDULE] [--reason REASON]
[--regime {sec-17a-4-audit-trail}]
{create,register-version,promote,set-retention,set-records-regime,deprecate,show,verify}
workflow_id
positional arguments:
{create,register-version,promote,set-retention,set-records-regime,deprecate,show,verify}
workflow_id
options:
-h, --help show this help message and exit
--by BY the principal performing the act (default: OS user)
--owner OWNER create: the accountable owner/team
--description DESCRIPTION
--criticality {tier-1,tier-2,tier-3}
create: tier-1 (critical) / tier-2 / tier-3 (standard)
--version VERSION the workflow_version label
--code CODE register-version: git sha / build id
--policy-version POLICY_VERSION
--regress-suite REGRESS_SUITE
register-version: reference to the signed regress
suite proving the version's behavioral delta
--notes NOTES
--to TO promote: the target environment
--from FROM_ENV promote: the source environment
--gate GATE promote: reference to the qualification/regress report
that gated it
--schedule SCHEDULE set-retention: CATEGORY=DURATION[,...], where DURATION
is <n>y (years), <n>m (calendar months) or <n>d
(days), e.g. adverse=7y,standard=3y
--reason REASON deprecate: why the workflow is withdrawn
--regime {sec-17a-4-audit-trail}
set-records-regime: the records regime the workflow
declares for its runs
exit codes:
0 OK - the evidence verifies, or the command did what it was asked
1 operational error - a usage error, a missing run or file, input that
cannot be read, or a license refusal: no verdict was reached
2 FAIL - the evidence does not verify, or a check it requires cannot run
on this install (a library is missing)
2 when `verify` finds the ledger does not verify