bide command reference
One program, bide, for everyone who does not import the library. Install it with brew install bide-ai/tap/bide or go install github.com/bide-ai/bide/cmd/bide@latest.
Every command parses its own flags with the standard library flag package: flags take one dash (-db, -evidence), and bide help <command> or bide <command> -h prints what is below. Exit status is 0 for success, 1 for a failure and 2 for a usage error, for every command but bide audit, which keeps its own statuses: only 0 means verified.
On a terminal the text output is colored (a green ✓ and a red ✗ beside the words, never instead of them); written to a file or a pipe it is plain. -color=auto|always|never sets it, and NO_COLOR (any value) or TERM=dumb turns auto off.
Built with -tags bide_audit_only, the program holds only audit, version and help, and its import graph is the standard library and the core module (see the security model).
| Command | What it does |
|---|---|
bide init | scaffold a project: a gated plan flow on SQLite (or, with -agent, an agent with a taint policy), with evidence for bide audit |
bide demo | kill an agent mid-payment and watch it not charge twice (no API key) |
bide doctor | check that a first run can work: Go, SQLite, the module cache, model keys, your project |
bide sample | write a sample journal of varied runs, with evidence and flow configs, and open bide view on it |
bide theme | check a theme file for the run viewer and the editor against the contrast and distinctness rules |
bide view | a read-only local page for one run of a journal, or a flow config's graph |
bide edit | a local page for a flow config: the graph, the approval gates, the assertions, and what an edit weakens; edit the source and save |
bide notify | set up and test the webhook notifier: test a receiver, run a local one, relay to Slack and PagerDuty |
bide journal | erase personal data from finished runs of a journal, accountably: a dry-run plan, then a signed record of each erasure |
bide approve | record your signed approval (or -reject) of a call that waits for a decision; -list shows what waits |
bide stop | stop agents now, as a pause that resumes when the stop is lifted: set a stop (-all, -tool, -flow, -agent), -list, -show and -lift; audited mode signs with an enrolled key |
bide identity | pre-flight a certificate-bound approval setup and say why a certificate would be refused (check), keep the CRLs of a policy's issuers current and archived (fetch-crl), and reset a poisoned rollback mark |
bide keygen | create an approver key pair for bide approve and print the public key policies and verifiers use |
bide migrate | create or check a Postgres journal's schema as its owner, so the service needs no DDL rights |
bide check | check plan flow configs, for CI: one file:node: message line per problem |
bide audit | produce and verify audit proofs offline |
bide version | print the version and the artifact formats bide audit reads (-json for JSON) |
bide init
Scaffold a project: a gated plan flow on SQLite (or, with -agent, an agent with a taint policy), with evidence for bide audit.
usage: bide init [-agent [-single-approver]] [-module <path>] [-dev <bide checkout>] <dir>
Writes a new project into dir, which must not exist or must be empty: main.go, color.go, main_test.go,
flow.yaml, README.md, .gitignore and go.mod. Then: cd <dir> && go mod tidy && go run .
With -agent the project is an agent instead of a plan flow: a tool that reads untrusted text, a refund,
and a taint policy that requires every tool and run to state its provenance, so a side effect asked for after the agent has read the text waits for an escalation
gate of two of three signed decisions, not counting the requester. -single-approver makes that gate one
unsigned decision, for a team of one; it is the weaker choice, and the README says so. A plan flow is not
covered by the taint policy.
-agent
write an agent with a taint policy (an escalation gate of two of three signed decisions) instead of a plan flow
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-dev string
a bide checkout to build against (replace directives), for a bide built from source
-module string
the module path (default: the directory's name)
-single-approver
with -agent: an escalation gate of one unsigned decision, for a team of one (weaker)
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide demo
Kill an agent mid-payment and watch it not charge twice (no API key).
Usage of bide demo:
-addr string
loopback address to serve the viewer on (port 0 picks a free one) (default "127.0.0.1:0")
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-fast
no pauses between steps, and exit 0 when the demo is done instead of serving the viewer (for CI; with -keep, bide view reopens the run)
-keep
keep the demo's directory (the journal, evidence and keys) and print it
-no-browser
print the viewer's address instead of opening a browser
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide doctor
Check that a first run can work: Go, SQLite, the module cache, model keys, your project.
usage: bide doctor [-dir <project>] [-offline] [-postgres-env <var>]
bide doctor -declarations <file>
bide doctor -diff <old.json> <new.json>
Checks that a first run of bide can work, and prints one line per check with a hint to fix a
failure:
Go the toolchain is installed and is Go 1.27 or later (older is a warning where
GOTOOLCHAIN=auto lets go fetch 1.27 itself, and a failure where it does not)
bide this bide against the latest release (skipped offline or on a build from source)
SQLite a journal can be created and written in a temporary directory
Postgres with the variable named by -postgres-env set, its DSN connects (the value is never printed)
model keys which of OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY and
GOOGLE_API_KEY are set (names only, never values); none is fine for the scripted demos
module cache GOPATH and the module cache are writable, so go mod tidy can download bide
project in a bide init project (go.mod and flow.yaml in -dir), the project builds
With -declarations, doctor reads the taint and cap declarations a host dumped from its agent (a
document of format bide.declarations.v1) and prints what a reader should look at: side-effecting tools
in an agent with no taint policy, exempt tools, cap-carrying tools, an escalation gate weaker than
need >= 2 with the requester excluded. With -diff it compares two such documents (the one on your main
branch and the one on your branch) and lists every change as WEAKENED, changed or strengthened: a
raised cap limit, a removed or renamed cap rule, a removed Untrusted, a new TaintExempt, require_provenance turned off, a lower need,
a requester no longer excluded. It exits 1 if anything is weakened, so a pipeline can gate on it. A
document written by a newer version, or one whose digest is not the digest of what it declares, is
refused. Neither report runs the first-run checks.
Both reports also read a flow's declarations: the plan.RegistryDescription of version 2 that a
program writes from its Registry (the file bide edit -blocks and bide check -blocks read), with
the flow's taint policy set by plan.DescribeTaintPolicy. It has no digest. A description of
version 1 carries no taint declarations: -declarations says taint is not known, and -diff reports
one weakened line when either side lacks them, and likewise when either gives no taint policy (an ungiven policy
is not "no policy"). Two files of different kinds are not compared.
Exit status is 0 when nothing failed (a warning does not fail), and 1 when a check failed. On a
terminal the output is colored; -color=never, or NO_COLOR set to any value, turns color off.
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-declarations file
report on the taint and cap declarations in file (a document the host dumps) instead of the first-run checks
-diff old.json new.json
compare two declarations documents, old.json new.json, and exit 1 if anything is weakened
-dir string
the directory to look for a bide init project in (default ".")
-offline
skip the checks that need the network (the latest release)
-postgres-env string
the environment variable holding a Postgres DSN to try; the check runs only if it is set (default "BIDE_POSTGRES_DSN")
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide sample
Write a sample journal of varied runs, with evidence and flow configs, and open bide view on it.
usage: bide sample [-out <dir>] [-no-browser] [-live] [-force]
Writes a sample journal into dir (default: the current directory) and opens bide view on it. No
API key, no network and no code needed: the runs are produced by the real runtime, driven by a
scripted model and fake tools. dir holds:
sample.db a SQLite journal of 14 runs: refund agent runs (completed, halted with an
unknown outcome, halted and resolved, waiting at a 2-of-3 approval gate,
approved, in progress, aborted, cancelled), plan flow runs, and a run of
durable steps only
*.evidence.json evidence packages for two runs, for bide audit and bide view -evidence
log.pub the public key the evidence is signed with
approver-keys.json the approvers' public keys, for bide view -approver-keys
flows/ three flow configs for bide view -config, bide check and bide check -diff
README.txt what is inside, and the commands to try
The runs are the same on every call: the same run IDs, states, start times and records, apart
from the random salt each record carries (so the digests over the records, and the evidence that
holds them, differ). The keys come from fixed public seeds: do not use them for anything real. The page is served read-only on
a loopback address; stop it with Ctrl-C.
-addr string
loopback address to serve the viewer on (port 0 picks a free one) (default "127.0.0.1:0")
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-force
replace an existing sample.db
-live
also keep one run, refund-live, progressing while you watch: it pauses at its approval gate, gets its two approvals and completes (about 20 seconds)
-no-browser
print the viewer's address instead of opening a browser
-out string
directory to write the sample into (created if missing) (default ".")
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide theme
Check a theme file for the run viewer and the editor against the contrast and distinctness rules.
usage: bide theme check [-v] <theme.json>...
check parses theme files and measures them against the rules in docs/design/themes.md
-v print every measure, not only the failures and warnings
Exit status:
0 every file passes its checks
1 a file is refused (it fails a check or is not a valid theme) or cannot be read
2 usage error: a bad flag or argument; nothing was readbide view
A read-only local page for one run of a journal, or a flow config's graph.
bide view: a read-only local web page for one run of a bide journal
bide view -db <file> [-run <id>] [flags]
bide view -postgres <dsn> [-run <id>] [flags]
bide view -postgres-env <VAR> [-run <id>] [flags]
bide view -journal <export.json> [-journal ...] [-run <id>] [flags]
bide view -config <flow.yaml|flow.json> [-check [-strict]]
bide view -config <flow.yaml|flow.json> -diff <old config|git revision> [-check [-fail-on-weaken]]
It shows an agent run's timeline (model turns, tool calls with their Safety, attempts, approvals,
halts, end state) or a plan flow's declared topology with the run's path (drawn from the topology
the run journaled, its digest checked, unless -topology overrides it), and whether the journal
verifies against a signed tree head or an evidence package; with -approver-keys, whether each
m-of-n approval gate's signatures verify (audit.VerifyApprovals), against the policy the gate
recorded or, with -need and -approvers, against the policy you expect. It never writes to the
store, and it serves on a loopback address only. Stop it with Ctrl-C.
With no -run the page opens on the run list: each run's kind, state (completed, halted: outcome
unknown, waiting for approval, in progress, aborted or cancelled), when it started (as its
run:start records it; none for a run an earlier version journaled) and its record count, newest
first, filtered by state, kind and run ID. Its headline links to the Needs attention list (/attention):
every run waiting for approval, halted with an unknown outcome or aborted, with the gate's
approvers and its deadline (gates with a deadline come first, the nearest first, and one due within
the hour is flagged; the rest are newest first) and the ResolveHalt call, and, from -db or -postgres, whether the notifier told someone and
the sink acknowledged it (the notification trail in the same database). The run list and that list are
built at most once every 2 seconds, so a page that reloads itself costs the store little. A
bide approve command shown there is quoted for a POSIX shell, also for a Windows -db path.
From -db or -postgres, the page of a run in progress follows it (live mode): it polls the store
about once a second for records after the last one it shows, and updates in place until the run
journals its end marker. An exported journal (-journal) is shown as it is.
With -config it shows a flow definition instead, without running anything: the declared graph,
its approval gates, and every problem plan.InspectConfig finds, marked on the node, edge or arm it
belongs to. The check is structural (types and registered blocks are checked when a program embeds
the viewer with its plan.Registry, see package plan/planview). Each node is colored by its crash
behavior (side effect, read-only, idempotent, or unknown without the Registry), and the config's
assert lines are decided on the graph, a violated one's counterexample path drawn in red. With
-check it serves nothing and prints one "file:node: message" line per problem ("file:from->to:
message" for an edge or arm), a violated assertion among them.
With -diff it compares the -config flow with an earlier version of it: the page draws the new flow
with added nodes and edges in green, removed ones as dashed red ghosts and changed nodes in amber,
and calls out an approval gate whose policy was weakened (removed, its need lowered, an approver
added without raising the need, exclude_principal dropped, or its timeout removed or lengthened),
a node that every path reached through a gate before and some path now reaches without one (whatever
its safety), a new effect no gate guards, a lowered safety, a Switch condition changed beside an ungated effect, a block changed on an ungated effect node without the Registry,
or an assert line removed, loosened, or kept and no longer holding (violated, undecided, or holding only
vacuously);
a gate made stricter (including a timeout added or shortened, which makes it fail closed sooner)
is marked strengthened. -diff takes a file, or, when no file has that name, a git
revision read with git show: <rev>:<path>, or a bare <rev> for the -config file's path at that
revision. With -check it serves nothing and prints one line per change and a summary line.
Exit status: 0 after a clean stop (or -h, or a -check that found no errors; warnings do not
count unless -strict; for -diff -check, a diff is not a failure), 1 if an input cannot be read,
the server fails, -check found errors (or, with -strict, any problem), or -diff -check
-fail-on-weaken found a weakened approval policy, 2 for a usage error.
Flags:
-addr string
address to serve on: a loopback IP (127.0.0.1 or ::1) or localhost, with a port (default "127.0.0.1:8484")
-approver-keys string
approver public keys, a JSON object of approver id to key text, e.g. {"ops":"ed25519:ab12..."}, to verify each m-of-n gate's signatures (audit.VerifyApprovals), or - for standard input, or a <(...) process substitution; needs -sth or -evidence
-approvers string
the expected policy's approver ids, comma-separated, in policy order; needs -need
-blocks string
with -config: a description of the program's registered blocks (json.Marshal of plan.Registry.Describe), to check blocks, types, safety and gates by name without the program; the result is labelled as per the file, not checked against the program
-check
with -config: serve nothing, print each problem as file:node: message, and exit 1 if any is an error; with -diff, print each change instead
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-config string
a flow config (.json, or .yaml/.yml) to show instead of runs: its declared graph and its problems; nothing runs
-db string
SQLite journal file to read, opened read-only (sqlite.OpenReadOnly)
-diff string
with -config: compare it with this earlier version, a file or else a git revision (<rev>:<path>, or <rev> for the -config path at rev); -check prints the changes instead of serving the page
-digest string
flow.Digest() of the -topology flow, compared with the digest the run journaled (default: computed from -topology when it carries the digest's inputs)
-evidence string
evidence package (audit.EvidencePackage JSON; - for standard input, or a <(...) process substitution) to verify; needs -pubkey
-exclude-principal
the expected policy excludes the run's requesters (its principal and those of the runs above it) from approving (separation of duties); needs -need
-fail-on-weaken
with -diff -check: exit 1 if an approval gate was removed or weakened
-journal value
exported journal (audit.ExportJournal as JSON) to read; repeatable
-need int
the expected policy's k: verify approvals against -need of -approvers instead of the recorded policy; needs -approvers and -approver-keys
-old-blocks string
with -diff: the description for the earlier version; without it the earlier version is checked structurally (-blocks is never applied to it)
-postgres string
Postgres journal to read, a pgx DSN such as postgres://user:pass@host:5432/db, read in sessions the server holds read-only (postgres.OpenReadOnly)
-postgres-env string
name of the environment variable that holds the Postgres DSN, instead of -postgres: keeps the password out of the argument list, and is the name the Needs attention list's bide approve commands use
-pubkey string
log public key as <scheme>:<hex>, or bare ed25519 hex, or a file holding it, or - for standard input, or a <(...) process substitution
-run string
run to open (default: the run list)
-sth string
signed tree head (audit.SignedTreeHead JSON; - for standard input, or a <(...) process substitution) to verify the journal against; needs -pubkey
-stop-policy string
the kill switch's stop policy (the JSON document bide stop -stop-policy reads; - for standard input, or a <(...) process substitution), so the banner and the held-by-stop states judge the control run as an audited deployment does and check its signatures; without it the control run is read as a basic one and the banner says signatures are not verified
-stop-root string
with -stop-policy: the digest of the deployment's root policy, when the file is a later policy the chain reaches
-strict
with -check: exit 1 on a warning too
-theme string
a theme file (JSON, see docs/guides/themes.md; check it first with bide theme check) the pages offer beside light, dark and high-contrast; refused, with the failed checks, and nothing served, if it is not valid or fails a contrast, distinctness or polarity check (C1 to C4, C8); the colour-blindness check (C6) only prints a warning
-theme-default string
the theme a reader starts in (light, dark, high-contrast, or the -theme file's name), instead of following the system setting; a reader's own choice still wins
-topology string
declared flow topology, JSON of flow.Topology(), to draw a flow run against instead of the topology the run journaled (flow:topology); for a run journaled before that record existed, or to check a run against another flow
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide edit
A local page for a flow config: the graph, the approval gates, the assertions, and what an edit weakens; edit the source and save.
usage: bide edit [-addr <host:port>] [-base <git revision>] [-blocks <description.json>] [-run <id>] [-db <file> | -postgres <dsn> | -postgres-env <VAR> | -journal <export.json>] [-theme <theme.json>] [-theme-default <name>] [-color auto|always|never] <flow.yaml|flow.json>
Opens a local page for one flow config: the declared graph, an outline of its nodes and wiring,
each node's approval gate and safety, the assertions and their verdicts, the problems bide check
finds, and the source. The page shows what bide check and bide view -config show for the file,
computed by the same code, and labels the check as structural: block and type names are checked
when a program loads the flow with its plan.Registry.
With -blocks, a description of the program's registered blocks (json.Marshal of plan.Registry.Describe),
the editor is typed: it lists the blocks in a palette with their types, safety and gates, checks the
types along every connection, shows the digest a run would journal, refuses an operation that
connects what does not fit, and knows the gate a block declares in Go when a block is changed. Every
typed result is labelled as resting on the file, not checked against the program: the check made
with the program's own plan.Registry is the control. A program can embed the editor beside its
Registry instead (package flowedit, WithRegistry).
With -run and a store (the same flags bide view takes, opened read-only), the page also compares the
file with the topology that run journaled: it says whether the file has the digest the run journaled
and, when it differs, what differs, by what the digest covers (flow name, entry, nodes, blocks, edges,
switch arms, gates when the blocks are known, and their order). That is a comparison of topologies and
nothing more: it does not say the run followed the file, which is conformance (bide view). A run that
is paused under a topology the file no longer has will not resume under the file. The page reads the
run once and again only when you press Reload run. With a store, with or without -run, the page's button,
Check unfinished runs, lists the store's unfinished runs by the digest each recorded and says which a drive
under this file (resume, recovery or restart) would refuse by the digest rule: a run whose digest is the
file's is not refused, a run of another flow is counted apart, and a run that has recorded no digest yet is
counted and not read. It reads one small record per run (at most 5000 runs, the first by run ID) and never a
history.
The page draws from checked themes: light, dark and high-contrast, which its header button steps
through, and the system's request for more contrast or forced colors is answered as bide view answers
it. -theme adds a theme file (see docs/guides/themes.md and bide theme check), which is refused, with
the failed checks, and nothing is served, if it is not valid or fails a check; -theme-default starts
the page in a theme. A program that embeds the editor can also lock it to one theme (package
flowedit, WithThemeLock).
You can edit the file's source in the page and see the check as you type; nothing is written until
you save, and a save shows the diff of the bytes it will write and the comments it removes. The page
compares the text with a baseline, the committed policy, and says so in a banner that stays while the file is weaker than
it: the file at git HEAD, or at the revision -base names (branch, tag or commit), or, when the file
is not in git, the file as it was when bide edit opened it. The comparison is the one bide check
-diff -check -fail-on-weaken makes.
It serves on a loopback address only (-addr, default 127.0.0.1:8585), answers only requests
addressed to a loopback host, and reads and writes only the file you name. The address it prints ends in a
fragment (#t=...) that carries a per-run session token; open that whole address. Stop it with
Ctrl-C. bide edit is not in a bide_audit_only build.
A save that weakens the policy against the baseline needs a confirmation that the server checks.
A save is refused, and writes nothing, if the file changed on disk since the page read it.
-addr string
address to serve on: a loopback IP (127.0.0.1 or ::1) or localhost, with a port (default "127.0.0.1:8585")
-base string
compare with the file at this git revision (a branch, tag or commit) instead of at HEAD; the file must be in it
-blocks string
a description of the program's registered blocks (json.Marshal of plan.Registry.Describe): typed mode, labelled as per the file, not checked against the program
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-db string
SQLite journal file to read, opened read-only (sqlite.OpenReadOnly)
-journal value
exported journal (audit.ExportJournal as JSON) to read; repeatable
-postgres string
Postgres journal to read, a pgx DSN such as postgres://user:pass@host:5432/db, read in sessions the server holds read-only (postgres.OpenReadOnly)
-postgres-env string
name of the environment variable that holds the Postgres DSN, instead of -postgres: keeps the password out of the argument list, and is the name the Needs attention list's bide approve commands use
-run string
a run of the journal to compare the file with: the topology it journaled, and what differs from the file (needs one of -db, -postgres, -postgres-env, -journal; a store without -run is for the list of unfinished runs)
-theme string
a theme file (JSON, see docs/guides/themes.md; check it first with bide theme check) the pages offer beside light, dark and high-contrast; refused, with the failed checks, and nothing served, if it is not valid or fails a contrast, distinctness or polarity check (C1 to C4, C8); the colour-blindness check (C6) only prints a warning
-theme-default string
the theme a reader starts in (light, dark, high-contrast, or the -theme file's name), instead of following the system setting; a reader's own choice still wins
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide notify
Set up and test the webhook notifier: test a receiver, run a local one, relay to Slack and PagerDuty.
usage: bide notify test -url <receiver> [-kind <kind>] [secret and TLS flags]
bide notify listen [-addr <host:port>] [secret flags]
bide notify relay [-addr <host:port>] [secret flags] [-slack-url-env ...] [-pagerduty-key-env ...]
Set up and test the webhook notifier (agent.WithNotifier with notify.NewWebhook):
test sends one signed sample notification to your receiver, with the same payload, signature
and TLS options the notifier uses, and reports the TLS handshake, the HTTP status, whether
the receiver acknowledged and how long each took
listen starts a local HTTPS receiver with a self-signed certificate that verifies each request
and prints the event, so test and listen check a whole setup on one machine
relay a receiver that verifies bide's webhooks and forwards them to Slack (Block Kit) and
PagerDuty (Events API v2), dropping redeliveries by delivery ID
The signing secret is read from an environment variable (default BIDE_WEBHOOK_SECRET) or a file
(-secret-file), never from a flag value, and is never printed or logged. Run bide notify <verb> -h
for a verb's flags. See docs/guides/notifications.md.
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide notify test
usage: bide notify test -url <receiver> [-kind <kind>] [-secret-env <VAR> | -secret-file <file>]
[-ca <file>] [-pin <hash>] [-client-cert <file> -client-key <file>] [-timeout <d>]
Sends one signed sample notification to the receiver at -url, the way the notifier sends a real
one (notify.NewWebhook: the same payload, signature, TLS 1.2+ and mutual TLS, CA and pin options),
and reports the TLS handshake, the HTTP status, whether the receiver acknowledged (answered 2xx)
and the timing. The sample is for a run that does not exist (its ID starts notify-test-); a relay
that forwards to Slack or PagerDuty forwards it too. The secret is never printed.
Kinds: approval_pending, approval_expired, outcome_unknown, run_aborted, recovery_failing, notification_overdue, resolved, escalated, stop_set, stop_lifted. A resolved is the all-clear of the approval_pending with the same -run: send that first, then
the resolved, to see a relay open and then close a PagerDuty incident.
Exit status: 0 the receiver acknowledged; 1 it did not; 2 usage error.
-ca string
verify the receiver against the CA certificates in this PEM file instead of the system roots
-client-cert string
present this client certificate (PEM) for mutual TLS; needs -client-key
-client-key string
the client certificate's private key (PEM)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-kind string
the kind of the sample notification: approval_pending, approval_expired, outcome_unknown, run_aborted, recovery_failing, notification_overdue, resolved, escalated, stop_set, stop_lifted (default "approval_pending")
-pin string
require the receiver's key to match this SPKI SHA-256 (64 hex characters or base64); two, comma separated, during a rotation
-previous-secret-env string
the environment variable that holds the previous secret, during a rotation (optional) (default "BIDE_WEBHOOK_SECRET_PREVIOUS")
-previous-secret-file string
read the previous secret from this file; used instead of -previous-secret-env
-run string
the sample's run ID (default: notify-test-<random>, a new event each time). Send an approval_pending and then a resolved for the same -run to test a relay's all-clear
-secret-env string
the environment variable that holds the signing secret (default "BIDE_WEBHOOK_SECRET")
-secret-file string
read the signing secret from this file, or - for standard input, or a <(...) process substitution (leading and trailing white space is dropped); used instead of -secret-env
-timeout duration
the request timeout (default 10s)
-url string
the receiver's URL, https (http only for localhost)
-view-db string
the journal file the payload's view command opens, as WithViewDB does
-view-url string
put a view link for the run viewer's base URL in the payload, as WithViewURL doesbide notify listen
usage: bide notify listen [-addr <host:port>] [-secret-env <VAR> | -secret-file <file>]
[-cert <file> -key <file>] [-client-ca <file>] [-ca-out <file>] [-json]
Runs a local HTTPS receiver that checks each request with notify.Verify (the signature, the
timestamp and the signed delivery ID) and prints the verified event, or why it was refused. Use it
with bide notify test, or point a real notifier at it, to see a whole setup work on one machine.
Without -cert and -key it makes a self-signed certificate for localhost, 127.0.0.1, ::1 (and the
host of -addr), valid for 24 hours, and writes it to a file (-ca-out, or a new file in the temp
directory) for the sender's -ca. It prints that file and the certificate's pin (the SPKI SHA-256
for -pin), and the command that tests it. The secret is never printed.
With -client-ca the receiver requires a client certificate signed by that CA (mutual TLS) and
prints the certificate's pin for each request.
It answers 204 to a verified request and 401 to any other; it forwards nothing and keeps nothing.
Stop it with Ctrl-C. Exit status: 0 after a clean stop; 1 failure; 2 usage error.
-addr string
the address to listen on (default "127.0.0.1:8443")
-ca-out string
write the generated certificate here (default: a new file in the temp directory)
-cert string
serve this certificate (PEM) instead of a generated one; needs -key
-client-ca string
require a client certificate signed by a CA in this PEM file (mutual TLS)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-json
print each verified payload as JSON, one line each, instead of a summary
-key string
the private key (PEM) of -cert
-previous-secret-env string
the environment variable that holds the previous secret, during a rotation (optional) (default "BIDE_WEBHOOK_SECRET_PREVIOUS")
-previous-secret-file string
read the previous secret from this file; used instead of -previous-secret-env
-secret-env string
the environment variable that holds the signing secret (default "BIDE_WEBHOOK_SECRET")
-secret-file string
read the signing secret from this file, or - for standard input, or a <(...) process substitution (leading and trailing white space is dropped); used instead of -secret-envbide notify relay
usage: bide notify relay [-addr <host:port>] [-cert <file> -key <file>] [-client-ca <file>]
[-secret-env <VAR> | -secret-file <file>]
[-slack-url-env <VAR> | -slack-url-file <file>]
[-pagerduty-key-env <VAR> | -pagerduty-key-file <file>] [-view-url <url>]
Receives bide's signed webhooks and forwards each verified notification to Slack and PagerDuty.
Point bide at it (notify.NewWebhook with the same secret); it needs no bide library or journal.
For each request it checks the signature, the timestamp and the signed delivery ID (notify.Verify)
and answers 401 to anything else. It then forwards to every configured destination and answers 204
only when all of them took the notification; if one failed it answers 502, and bide sends the event
again. Because bide's delivery is at least once, the relay remembers the delivery IDs it forwarded
(-dedupe of them; -state keeps them across a restart) and acknowledges a repeat without forwarding it again; after a partial failure
only the destination that failed is tried again.
Slack an incoming webhook URL: a Block Kit message with the run, kind, summary, deadline,
who may approve, and an "Open in viewer" button when there is a link (the payload's
view.url, else -view-url plus the run ID). The URL is a credential: it is read from
the environment or a file, and never printed or logged.
PagerDuty Events API v2: a trigger whose dedup_key is the event's ID (the same on every
delivery, so PagerDuty collapses repeats) and a resolve for an all-clear notification.
The routing key is read like the Slack URL.
A destination is on when its variable is set or its file is named; at least one is needed. The
relay never forwards error text or tool arguments, even if bide sends them. bide requires an https
URL for a receiver (http only for localhost), so give -cert and -key, or run the relay behind a
proxy that terminates TLS on the same host. Forwarding has a budget (-forward-timeout) below bide's
10 s request timeout. Stop it with Ctrl-C. Exit status: 0 after a clean stop; 1 failure; 2 usage.
-addr string
the address to listen on (default "127.0.0.1:8080")
-cert string
serve TLS with this certificate (PEM); needs -key. Without it the relay speaks plain http
-client-ca string
require a client certificate signed by a CA in this PEM file (mutual TLS); needs -cert
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-dedupe int
how many delivery IDs to remember (default 10000)
-forward-timeout duration
the budget for forwarding one delivery; keep it below bide's request timeout (10 s) (default 8s)
-key string
the private key (PEM) of -cert
-pagerduty-key-env string
the environment variable that holds the PagerDuty Events API v2 routing key (default "PAGERDUTY_ROUTING_KEY")
-pagerduty-key-file string
read the PagerDuty routing key from this file; used instead of -pagerduty-key-env
-pagerduty-url string
the PagerDuty Events API endpoint (the EU region has its own) (default "https://events.pagerduty.com/v2/enqueue")
-previous-secret-env string
the environment variable that holds the previous secret, during a rotation (optional) (default "BIDE_WEBHOOK_SECRET_PREVIOUS")
-previous-secret-file string
read the previous secret from this file; used instead of -previous-secret-env
-secret-env string
the environment variable that holds the signing secret (default "BIDE_WEBHOOK_SECRET")
-secret-file string
read the signing secret from this file, or - for standard input, or a <(...) process substitution (leading and trailing white space is dropped); used instead of -secret-env
-slack-url-env string
the environment variable that holds the Slack incoming webhook URL (default "SLACK_WEBHOOK_URL")
-slack-url-file string
read the Slack webhook URL from this file; used instead of -slack-url-env
-state string
keep the delivery IDs forwarded and the events cleared in this file, so they survive a restart (without it a restart forgets them); one relay per file, enforced by a lock
-state-flush duration
with -state: how long a change may wait so a burst costs one file write; a clear is always written at once, and a crash can lose the last window of forwarded-delivery entries (negative: write every change) (default 1s)
-view-url string
the run viewer's base URL, for the "Open in viewer" button when a notification has no view.urlbide journal
Erase personal data from finished runs of a journal, accountably: a dry-run plan, then a signed record of each erasure.
usage: bide journal redact (-db <file> | -postgres-env <var> [-schema <name>]) -run <id> <selection>
[-execute -plan-digest <hex> -reason <text> -ticket <id> -sign-key <file> -head-out <file> ...]
redact replace the content of records of a finished run with tombstones that keep each record's
position, name and leaf hash, so the run's signed heads and every other record's proof
still verify, and record the erasure in a signed trail. Run bide journal redact -h.
hold place, lift and list legal holds: the store refuses to erase a held run, and the signed
redaction trail records who placed and lifted each hold. Run bide journal hold -h.
acknowledge sign a note that a leaf in the redaction trail that the tool did not write (a planted
one that bide audit redactions reports) has been investigated; the audit then reports it as
acknowledged. Run bide journal acknowledge -h.
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide journal redact
usage: bide journal redact (-db <file> | -postgres-env <var>) -run <id> (-name <key> | -prefix <p> | -kind <k> | -payloads)...
A dry run (the default) prints, for each run, whether it can be erased and the records it would
replace: position, key, kind, length and leaf hash, never content, and a plan digest. Review it, then
run the same command with -execute -plan-digest <digest> -reason ... -ticket ... -sign-key ... -head-out ...
Before erasing, make every piece of evidence you will need: a journal that holds a tombstone can no
longer produce a new absence proof, run certificate or event stream. The command refuses to erase a
run that no signed journal head (-sth, verified under -pubkey) covers, unless -allow-uncovered.
It refuses a run that is not over, whose lease is live (probed by taking the lease and giving it back; a role that cannot take a lease skips the probe and the store's own refusal applies), whose parent is not over, that belongs to a
session, that holds protected records (they are kept and listed), and a run the event store holds
events of (unless -keep-event-copies). It writes a "begin" record to the redaction trail before it
erases and an "end" record after; if it stops partway, run the same plan again.
-accept-unheaded-trail
with -execute: sign the trail although it already holds records and no earlier head (-head-out) attests them, so they are attested only from this head on; never needed on a trail's first erasure
-allow-uncovered
with -execute: erase although no signed head covers the run (recorded in the trail as UNCOVERED, and reported by bide audit redactions)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-db string
the SQLite journal to erase from
-deployment string
with -execute: the deployment name signed into every trail record (required): records cannot be copied between deployments that share a key
-execute
erase; without it the command only lists the plan
-head-out string
with -execute: append the trail's new signed head, as one JSON line, to this file, for your anchor
-include-approvals
let the selection also erase approval decisions, which verify-approvals and decision coverage read
-json
print the plan and result as one JSON document
-keep-event-copies
with -execute: erase although the event store holds events of the run, which stay (recorded)
-kind value
erase the records of this kind (model, tool_result, value, signal, approval); repeat
-name value
erase the record with this key; repeat
-payloads
erase every record whose content is payload: the input and principal, model turns, tool results, user steps, signals, approval requests (never an end marker, which is erased only by naming it; never a protected record, never an approval decision unless -include-approvals)
-plan-digest string
with -execute: the plan digest a dry run printed; the erasure runs only if the plan is still exactly that
-postgres-env string
the environment variable that holds the Postgres DSN of a role that can read the journal (never given on the command line)
-prefix value
erase the records whose key starts with this; repeat
-pubkey string
with -execute: the log's public key (ed25519:<hex>, a file, or - for standard input, or a <(...) process substitution) that verifies the -sth heads
-reason string
with -execute: why (recorded in the trail)
-redact-postgres-env string
the environment variable that holds the DSN of the role that may erase (EXECUTE on bide_redact_v3 and no table privilege); default: the -postgres-env role
-run string
the run to erase from
-schema string
with -postgres-env: the schema that holds the journal (recommended; without it the DSN's search path decides)
-sign-key string
with -execute: the log signing key file that signs the redaction trail's head (never printed)
-sth value
with -execute: a signed journal head of the run; one that verifies, matches the journal and covers all of it is required; repeat
-subruns
also erase from the run's sub-agent runs (each is planned and recorded on its own)
-ticket string
with -execute: the ticket or authority (recorded in the trail)
-trail-db string
keep the redaction trail in this SQLite file instead of the journal's (recommended: a store the erasing role cannot rewrite)
-trail-postgres-env string
keep the redaction trail in the Postgres database whose DSN is in this variable, instead of the journal'sbide journal acknowledge
usage: bide journal acknowledge (-db <file> | -postgres-env <var> | -trail-db <file> | -trail-postgres-env <var>)
-position <n> -reason <text> -ticket <id> -deployment <name> -sign-key <file> -head-out <file>
Acknowledges a leaf in the redaction trail that the redaction tool did not write: one that bide audit
redactions reports as BAD_SIGNATURE, REORDERED or MALFORMED. Investigate it first (who could append to
the event store?). The acknowledgement is a signed record naming the leaf's position and the hash of its
bytes, with the reason, the ticket and who; the audit then reports that leaf as acknowledged and stops
failing on it. It acknowledges nothing else: not a record the tool wrote, not an erasure made by hand, and
not another leaf later at that position. It cannot be undone: the trail is append-only.
-accept-unheaded-trail
sign although the trail holds records and no earlier head attests them
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-db string
the SQLite journal whose event store holds the redaction trail
-deployment string
the deployment name signed into every trail record (required)
-head-out string
the file of the trail's signed heads: it is read for the earlier heads and the new head is appended to it
-position int
the position in the trail of the leaf to acknowledge (bide audit redactions names it in its finding) (default -1)
-postgres-env string
the environment variable that holds the Postgres DSN of a role that can append to the event store (never given on the command line)
-reason string
what was found, in words (recorded)
-schema string
with -postgres-env: the schema that holds the journal
-sign-key string
the log signing key file that signs the acknowledgement and the trail's head (never printed)
-ticket string
the ticket or authority (recorded)
-trail-db string
the SQLite file that holds the redaction trail, when kept apart from the journal
-trail-postgres-env string
the environment variable that holds the DSN of the Postgres database that holds the redaction trailbide journal hold
usage: bide journal hold place (-db <file> | -postgres-env <var>) -id <hold> -matter <text> -run <id>... [-tree]
-reason <text> -ticket <id> -deployment <name> -sign-key <file> -head-out <file>
bide journal hold lift (-db <file> | -postgres-env <var>) -id <hold> -reason <text> -ticket <id>
-deployment <name> -sign-key <file> -head-out <file>
[-authorization <file> -authorizer-pubkey <key>... [-require-authorization]]
bide journal hold authorize (-db <file> | -postgres-env <var>) -id <hold> -reason <text> -ticket <id>
-deployment <name> -trail-pubkey <key> -authorizer-key <file> -out <file>
[-valid-for <duration>] [-lifter-key-id <id>] [-execute]
bide journal hold list (-db <file> | -postgres-env <var>)
place keep the named runs (and with -tree the sub-agent runs below them) from being erased; one hold
can name several runs, so a matter is one hold. The store enforces it first, then the placement
is recorded in the signed redaction trail.
lift record the lift in the trail first, then remove the hold; a hold is never lifted without evidence.
authorize a second person signs, with a key of their own, their consent to lift one hold, bound to the
placement in force, the deployment and a validity; without -execute it shows what it would sign.
lift -authorization checks it first and embeds it in the lift's record; -require-authorization
refuses a lift without one. bide audit redactions checks it offline (LIFT_UNAUTHORIZED).
list the holds in force in the store.
A hold stops bide's own erasure. It does not stop a database administrator, a restore or a hand-written
DELETE, and it does not protect the anchor (an object-store legal hold on the anchor is a separate
control). On Postgres the connecting role needs SELECT, INSERT and DELETE on the holds table and nothing
else; the role that erases cannot read or change it.bide approve
Record your signed approval (or -reject) of a call that waits for a decision; -list shows what waits.
bide approve: record a signed approval, or a rejection, of a call that waits for a decision
bide approve -db <file> -run <id> -call <tool-use id> -as <approver> -key <key-file> [flags]
bide approve -postgres-env <VAR> -run <id> -call <tool-use id> -as <approver> -key <key-file>
bide approve -db <file> -list
bide approve -to <url> -run <id> -call <tool-use id> -as <approver> -key <key-file> -approver-keys <file>
It reads the call from the journal, never from a flag or a notification, and shows what it is
about to sign: the run, the tool, the call's arguments (indented JSON, long ones cut; -full shows
all), the gate (k of n, who has decided, who is pending) and the SHA-256 of the arguments the
signature binds. It then asks you to type your approver id (or y) to confirm; -yes skips the
question, for scripts. The decision is signed with your private key (made by bide keygen: Ed25519, ECDSA P-256, ML-DSA-65 or hybrid),
checked against the call before it is recorded, and recorded with the time you decided.
It refuses, and records nothing, when the call has no waiting gate, the run is not waiting on it,
the gate already passed or was denied, you are not one of the gate's approvers, you already decided
the other way (it says what, and when), or the key file can be read by others (on Unix, as ssh refuses one). It
checks again after you confirm, in case the gate was decided or the run ended while you read. If
your counted decision is the one you are making again (approve after approve, reject after reject),
it signs and writes nothing, prints "already recorded: your approve at <time> counts; nothing to do"
and exits 0, so a retry after a lost response is safe, under every scheme. It
never refuses, and -list never settles a gate, on records it has not verified: without
-approver-keys the standing is labelled unverified. A call whose approval-pending note was lost (the
note is the journal's only record of the gate's policy) is refused with a precise message: the
approvers and the count shown must come from the journal, never from a flag.
If the arguments are longer than the view (40 lines, 200 characters a line), bide approve will not
sign: the signature binds all of them, and what it hid could be what matters. Rerun with -full. If
you and another terminal decide as one approver at once, both decisions are recorded, the first
valid one counts, and the other command exits 1 ("another decision of yours counts").
An m-of-n decision needs -approver-keys, a JSON object of approver id to public key (the file bide
view -approver-keys reads; bide keygen -as <id> prints an entry): the journal holds approver ids,
not keys, so this file is the only way to check that your key is the one the application enrols. It
refuses a key that is not the one enrolled for you before recording anything, and prints a verified
tally. -unverified decides without it: the decision is recorded even if the key is not the enrolled
one (then it never counts), a warning says so, and the tally printed counts the decisions recorded,
labelled unverified. A single-approver gate has no signature, so it takes neither.
A single-approver gate (agent.Approve) has no approver identity and no signature: bide approve
records the decision as agent.Approve does, takes neither -as nor -key, and says so.
-reject records a rejection: the same checks, the same signature over a denial. One command with a
flag keeps the checks in one place; a rejection is the same act with the opposite byte, and the
confirmation prompt says REJECT in capitals.
An m-of-n decision also leaves a receipt (-receipt, default next to -key; mode 0600, never
overwritten): the signed decision with the call's arguments, the journal record's name and position,
and when it was recorded; no key material. The decision is signed into the audit log at the app's
next write to the run (bide approve cannot tell whether the application audits the journal, so it
says this either way). -verify-receipt <file> -approver-keys <keys> checks a receipt on its own,
reading no journal; bide audit verify-receipts checks receipts against the journal and its signed
heads, and flags a decision deleted after signing.
-to <url> decides through an application's approval intake (package approvals) instead of writing a
journal, for an approver with no database access: the application records the signed decision through
its own journal, so its audit log signs it as it is written. The call is fetched from the endpoint and
shown, and what is signed is what is shown: the command computes the SHA-256 of the arguments it
displays and refuses an endpoint whose own digest differs, shows the digest it computed, and signs
that. The endpoint verifies the signature against the call it holds, so arguments shown that are not
the journal's produce a decision that records nothing. The same refusals apply (the call is not
waiting, you are not an approver, you already decided), and the gate is read again after you confirm.
The URL must be https (http only to a loopback address), carry no credentials, and a redirect is
not followed. -tls-ca names the CA that signs the endpoint's certificate (instead of the system
roots), -client-cert and -client-key present a client certificate for mutual TLS, and -token-env
names an environment variable that holds a bearer token to send. -to serves m-of-n gates (a
single-approver gate has no signature), and -list does not go with it. The decision's receipt is
the one the endpoint returns, checked against what you signed and against your key before it is
written. If the request fails with no answer, the decision may or may not have been recorded: run
the command again, and a decision of yours that counts is refused as already decided.
-cert <chain.pem> signs a certificate-bound decision: the approver is identified by a certificate from the
bank's CA, not by an enrolled key. The decision is signed over the bide.approval.v4 bytes (which bind the
SHA-256 of your leaf certificate) with the key of the leaf, and travels with the chain, which the gate
checks when it counts the decision. The file holds CERTIFICATE blocks only, the leaf first (at most 8
certificates); a private key block in it is refused. Before anything is signed the command checks that the
key (-key, a key file, or an HSM or KMS key for bide-hsm) is the key of the leaf, by comparing the keys, that
the certificate is valid now and has at least -cert-min-left (60 seconds) left, and, with -identity-policy
<policy file> (the certificate policy: trust anchors, pinned intermediates, the approver-to-identity map),
that the policy accepts the chain for -as; -unverified signs without the policy check and says so. No
failure falls back to a bare-key decision. A certificate-bound approver of the gate (the journal's pause
note says who) must use -cert, and a bare-key approver of such a gate must not: the other would be recorded
and never counted. -approver-keys does not apply to a certificate-bound decision. The command cannot tell
you the gate counted it: the gate needs a signed tree head over the decision and current revocation status;
see docs/guides/certificate-approvers.md.
After the decision is recorded, re-run the run's root run ID (agent.Run with the same ID) or let
RecoverLoop pick it up: the gate counts the decisions and the call runs or is denied. bide approve
never runs the call.
-list prints the calls in the journal that wait for a decision, each with the bide approve command
that decides it and, for a gate with a deadline (ApprovalPolicy.Timeout), the time left; a gate
past its deadline is marked and gets no command, since it refuses decisions. -json prints them as JSON. With -approver-keys it counts each gate as the gate does
(verified); without it the counts are labelled unverified and no gate is called settled. Run and
call ids that hold control, bidirectional or invisible characters get no command (take their ids from -json and give that call to -item). A Postgres journal is named by -postgres-env, the name
of the environment variable that holds the DSN, so the password stays out of the argument list,
the shell history and the commands -list prints; -postgres takes the DSN itself, and the listed
commands then name $BIDE_POSTGRES_DSN.
A key in an HSM, on a smart card or token, or in a cloud KMS is used by bide-hsm approve, a separate
program (the PKCS#11 library needs cgo, which this one is built without): the same command, with
-key naming the key by reference, a PKCS#11 URI or a KMS key ARN, in place of a key file.
go install github.com/bide-ai/bide/cmd/bide/bide-hsm@latest builds it.
Exit status: 0 on success (for -list, even when nothing waits), 1 if the command refused or
failed, 2 for a usage error.
Flags:
-approver-keys string
approver public keys, a JSON object of approver id to key text, e.g. {"ops":"ed25519:ab12..."}, the file bide view -approver-keys reads, or - for standard input, or a <(...) process substitution (which then also needs -yes) (bide keygen -as prints an entry): refuse a -key that is not the one enrolled for -as, and verify the tally. Required for an m-of-n gate unless -unverified
-as string
your approver id, exactly as the gate's policy lists it (not for a single-approver gate)
-call string
the call's tool-use ID (for a plan flow node, its key, such as node:review)
-cert string
sign a certificate-bound decision (bide.approval.v4) with your certificate chain: a PEM file, leaf first, the leaf being the certificate of -key. The key must be the leaf's key (checked before anything is signed), and with -identity-policy the chain must be accepted for -as at this moment. Never falls back to a bare-key decision
-cert-min-left duration
with -cert: the least validity the leaf must have left, so the decision is provable before the certificate expires (default 1m0s)
-client-cert string
with -to: a PEM client certificate for mutual TLS (with -client-key)
-client-key string
with -to: the PEM private key of -client-cert
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-db string
SQLite journal file
-full
show all of the call's arguments, not the first lines
-identity-policy string
the certificate policy file (trust anchors, pinned intermediates, the approver-to-identity map; see docs/guides/certificate-approvers.md). With -cert: your chain must be accepted for -as by it at this moment, before anything is signed. With -verify-receipt, for a certificate-bound receipt: the chain and identity are checked against it at the time the receipt's anchoring head was signed; revocation status is not checked
-item string
take -run and -call exactly from one call of bide approve -list -json output instead: a file, or - for standard input, or a <(...) process substitution (which then also needs -yes, since the confirmation would read the same input). The input is one call's object, or an array of exactly one. For ids that cannot be pasted on a command line (a line break or an invisible or bidirectional character in them)
-json
with -list: print the waiting calls as JSON
-key string
your private key file, as bide keygen writes it (Ed25519, ECDSA P-256, ML-DSA-65 or hybrid) (not for a single-approver gate); on Unix it must not be readable by group or others
-list
list the calls that wait for a decision, each with its bide approve command; nothing is recorded
-log-key string
with -verify-receipt, for a certificate-bound receipt: the audit log's public key (ed25519:<hex>, or a file holding it, or - for standard input, or a <(...) process substitution, which then also needs -yes), which vouches for the receipt's anchoring proof
-postgres string
Postgres journal, a pgx DSN such as postgres://user:pass@host:5432/db; prefer -postgres-env, which keeps the password out of the argument list
-postgres-env string
name of the environment variable that holds the Postgres DSN
-receipt string
where to write the decision receipt (default: next to -key, named <run>-<call>-<approver>.receipt.json); mode 0600, never overwritten
-reject
record a rejection instead of an approval
-run string
the run whose journal holds the call: the pause's run ID
-tls-ca string
with -to: the PEM CA certificate(s) that sign the endpoint's certificate, instead of the system roots
-to string
decide through an application's approval intake (package approvals) at this base URL (https, or http to loopback) instead of writing a journal: the call is fetched from the endpoint, shown, signed and posted
-token-env string
with -to: name of the environment variable that holds a bearer token to send (the token never goes on the command line)
-unverified
decide an m-of-n gate without -approver-keys: the key is not checked against the one enrolled for you, and the tally is not verified
-verify-receipt string
verify a decision receipt on its own, against -approver-keys, instead of deciding anything: its signature over the exact call it states
-yes
do not ask for confirmation (for scripts); what is signed is still shown
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide stop
Stop agents now, as a pause that resumes when the stop is lifted: set a stop (-all, -tool, -flow, -agent), -list, -show and -lift; audited mode signs with an enrolled key.
bide stop: stop agents now (a pause that resumes when the stop is lifted), and list and lift stops
bide stop -db <file> -all|-tool <name>|-flow <name>|-agent <name> -reason <text> [-yes]
bide stop -db <file> -list [-json]
bide stop -db <file> -show <id>
bide stop -db <file> -lift <id> -reason <text> [-yes]
bide stop -postgres-env <VAR> ...
A stop is a pause, not a failure: a call that has begun finishes, a call that has not begun does not start,
and the runs carry on when the stop is lifted. There is no default scope: a bare "bide stop" lists the active
stops and exits 2, and never sets one. -tool, -flow and -agent repeat (one stop each).
Basic mode (no -stop-policy) needs no keys: anyone who can reach the journal sets and lifts a stop, and who
did it is asserted, not authenticated. Audited mode (-stop-policy FILE, the deployment's policy) signs every
record with -key as the enrolled approver -as, lifts by the policy's quorum (each lifter runs -lift), and
writes the signed stop trail that "bide audit stops" verifies. Give every process the same mode: a basic
process that meets signed records holds side-effect calls until it is given the policy.
An -agent stop covers runs whose identity (agent.WithIdentity) names that agent; a run with no identity is
never covered by one. Use -all or -tool to cover those.
Operations on an audited deployment:
-reaudit append to the trail the records the control run has and the trail lacks (after exit 5)
-apply-pending make effective the signed lifts (and policy or mode records) that sit on the trail and never
took effect, after showing each one's signer and age; signed, so who applied what is evidence
-upgrade move to audited mode: adopts the active plain stops as signed ones, then records the change
-downgrade record a move back to basic; refused while any stop is active
The reason is shown in logs, notifications and the viewer: put no secret and no customer data in it. A stop is
written without a prompt when -yes is given or standard input is not a terminal, and asked about once on a
terminal. A lift, -apply-pending, -upgrade and -downgrade ask on a terminal and refuse without one unless -yes
is given. The journal is named by -db (an existing SQLite file) or -postgres-env (the variable that holds the
DSN: it never goes on the command line).
Flags:
-agent value
set a stop that holds runs of this agent, by its identity's actor name (repeat for several); runs with no identity are not covered
-all
set a stop that covers every run
-apply-pending
audited: make effective the signed records on the trail that never took effect, after showing each one's signer and age (signed, so it is evidence)
-as string
audited mode: your approver id, as the stop policy lists it; basic mode: the name recorded (default your OS user; asserted, not authenticated)
-block-compensation
with a stop: hold a saga's compensation too (by default a rollback continues)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-db string
SQLite journal file (must exist)
-downgrade
record a move back to basic mode (refused while any stop is active)
-flow value
set a stop that holds this plan flow, by its name (repeat for several)
-json
with -list: print the state as JSON
-key string
audited mode: your private key file, as bide keygen writes it; on Unix it must not be readable by group or others
-lift string
add your lift of this stop (its ID or an unambiguous prefix of at least 8 characters); audited mode lifts by the policy's quorum
-list
list the stops: active ones with who set them and their lifts, the rejected records, the records waiting on the trail; nothing is written
-postgres-env string
name of the environment variable that holds the Postgres DSN (a DSN never goes on the command line)
-reason string
why (at most 1 KiB, shown in logs, notifications and the viewer: no secrets, no customer data); required to set or lift
-reaudit
audited: append to the stop trail what the control run has and the trail lacks
-show string
show one stop, by its ID or an unambiguous prefix of at least 8 characters, with its lift records
-stop-policy string
audited mode: the stop policy file, or - for standard input, or a <(...) process substitution (JSON: approvers' public keys, setters, lifters, lift quorum, deployment ID) the deployment pins; without it this is basic mode
-stop-root string
audited mode: the digest of the deployment's root policy, when -stop-policy is a later policy the chain reaches
-tool value
set a stop that holds calls to this tool, by exact name (repeat for several)
-upgrade
move the deployment to audited mode: adopt the active stops as signed ones and record the change (needs -stop-policy, -as, -key)
-yes
do not ask for confirmation (for scripts); what is signed is still shown
Exit status:
0 success
1 refused or failed: the stop control did not accept the record, no such stop, the prompt was declined,
or the stops cannot be judged (the stops are unknowable); nothing was written unless stated
2 usage error: a bad flag or argument; nothing was read or written. A bare "bide stop" is one
3 the journal, the policy or the key could not be read or opened; nothing was written
5 half done: an audited record landed in the control run or on the stop trail but not both. The
message says which; "bide stop -reaudit" (a stop in force, trail missing) or "bide stop
-apply-pending" (a lift on the trail, not in force) completes it. Repeating a stop only reports
it in force (nothing is written), so it repairs nothingbide identity
Pre-flight a certificate-bound approval setup and say why a certificate would be refused (check), keep the CRLs of a policy's issuers current and archived (fetch-crl), and reset a poisoned rollback mark.
usage: bide identity fetch-crl -policy <file> -params <file> -cache <dir> [-once]
bide identity check -policy <file> -params <file> (-expect <file> | -expect-digest <hex> | -no-expect) (-crl-dir <dir> | -fetch | -no-status) [-cert <chain.pem>] [-json]
bide identity reset-high-water -policy <file> -params <file> -cache <dir> -issuer <hex> -reason <text> -operator <name> [-set-aside <hash>]... [-accept-lost-listings]
bide identity ack-reset -policy <file> -params <file> -cache <dir> -issuer <hex> -name <RESET-...json>
Keep the CRLs of a certificate policy's issuing CAs current and archived:
fetch-crl fetches the CRLs from the URLs in the policy file's "crl" member (http and https
only), verifies each against its issuer's own certificate, refuses rollbacks and
equivocation, and writes the dated archive. With -once it makes one pass and exits
1 unless every issuer holds a fresh CRL (a cron job); otherwise it runs until
interrupted.
check the pre-flight before go-live, and when an approver's decision is refused: does
the policy load, do the pinned CAs and intermediates match, are the CRLs reachable
and fresh enough for the declared ages, do the policy file and -params agree with the
gate's recorded policy, and would the gate accept an approver's certificate (given with
-cert) and let its call run. It runs the gate's own code for each answer and prints
one line per check with the fix, and what it cannot check ahead of time. Exit 0 ready,
1 will not work as configured, 2 usage, 3 a file could not be read, 4 nothing failed but
part was left unchecked (-no-status, -no-expect).
reset-high-water the way out of a poisoned rollback mark (a CA that issued one CRL with a mistaken
huge number, or restarted its numbering): sets aside the CRL at the mark, with a
durable record, so a restart cannot bring the mark back.
ack-reset acknowledges a reset record; until then every start reports it.
The CA timings come from the -params file, which must carry the values the gate declares. Standard
output is one JSON line per event. A gate process embeds the same refresher (crlrefresh.New);
this command is for the archive an audit kit reads and for monitoring. See
docs/guides/certificate-approvers.md.
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was read
for identity check: 1 means the setup will not work as configured (a check failed)
3 identity check: a file could not be read or the tool could not run
4 identity check: nothing failed, but part was left unchecked (-no-status, -no-expect): not readybide identity fetch-crl
usage: bide identity fetch-crl -policy <file> -params <file> -cache <dir> [-once] [-health-every <duration>]
-cache string
the archive directory (created 0700; one that others can write to is refused)
-health-every duration
how often a running fetch-crl prints a health line per issuer (0 prints none; -once prints one at the end) (default 5m0s)
-once
make one pass over every issuer and exit 1 unless each holds a fresh CRL (for cron); without it, run until interrupted
-params string
the declaration of the CA timings (ca_period, max_status_age, exec_status_age, per-issuer values)
-policy string
the certificate policy file (anchors, intermediates, and the crl and intermediate_certs members)bide identity check
usage: bide identity check -policy <file> -params <file> (-expect <file> | -expect-digest <hex> | -no-expect) (-crl-dir <dir> | -fetch | -no-status) [-cert <chain.pem> [-chain <more.pem>] [-as <approver id>]] [-at <time>] [-json]
-as string
the approver id the certificate is for (default: the policy's only approver id)
-at string
judge at this time, RFC 3339 (default now); not with -fetch
-cert string
an approver's certificate chain, PEM, leaf first (as bide approve -cert takes it): is it accepted for the approver, as a decision made now, and would the call run
-chain string
more certificates (PEM) to carry behind -cert, such as an intermediates bundle
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-crl-dir string
offline: read the CRLs from this directory (a bide identity fetch-crl archive, which is not written to, or a flat directory of .crl, .der or .pem files); no network is used
-expect string
the gate's recorded policy: the "policy" member of its identity record (or the whole record), to compare the policy file and -params with, member by member
-expect-digest string
the gate's policy digest (lowercase hex SHA-256: the pause note's identity_policy_digest, or the identity record's policy_digest): compared with the digest of the policy file and -params, which is an equality only when -params states every member the digest covers (w, min_w, routine_grace, clock_tolerance, coverage_tolerance, allow_holds, consecutive_numbers, retained, effective_from); otherwise the check fails and names the missing members
-fetch
online: fetch the CRLs from the policy's crl sources (http and https only, with the size limits, timeouts and same-host redirect rule of fetch-crl; nothing is stored). Run it on the gate's host
-json
print the report as one JSON document
-no-expect
do not compare with the gate's recorded policy or digest; the result is then partial (exit 4) and never ready
-no-status
do not check CRL status; the result is then partial (exit 4) and never ready
-params string
the declaration of the CA timings (ca_period, max_status_age, exec_status_age, per-issuer values): a copy of what the gate declares
-policy string
the certificate policy file the gate loads (the same file bide identity fetch-crl takes)bide identity reset-high-water
usage: bide identity reset-high-water -policy <file> -params <file> -cache <dir> -issuer <hex> -reason <text> -operator <name> [-set-aside <sha256 hex>]... [-accept-lost-listings]
-accept-lost-listings
allow the reset although a CRL set aside lists a revocation that no remaining CRL lists (the serials are recorded)
-cache string
the archive directory (created 0700; one that others can write to is refused)
-issuer string
the issuing CA, as the lowercase hex SHA-256 of its public key (SubjectPublicKeyInfo)
-operator string
who resets it (recorded in the archive)
-params string
the declaration of the CA timings (ca_period, max_status_age, exec_status_age, per-issuer values)
-policy string
the certificate policy file (anchors, intermediates, and the crl and intermediate_certs members)
-reason string
why the mark is reset (recorded in the archive)
-set-aside value
the SHA-256 (hex) of an archived CRL to set aside; repeatable. Without it, the archived CRL at the current markbide identity ack-reset
usage: bide identity ack-reset -policy <file> -params <file> -cache <dir> -issuer <hex> -name <RESET-...json>
-cache string
the archive directory (created 0700; one that others can write to is refused)
-issuer string
the issuing CA, as the lowercase hex SHA-256 of its public key (SubjectPublicKeyInfo)
-name string
the reset record's file name, as the start-up report gives it
-params string
the declaration of the CA timings (ca_period, max_status_age, exec_status_age, per-issuer values)
-policy string
the certificate policy file (anchors, intermediates, and the crl and intermediate_certs members)bide keygen
Create an approver key pair for bide approve and print the public key policies and verifiers use.
usage: bide keygen -out <key-file> [-as <approver id>] [-alg ed25519|ecdsa-p256|ml-dsa-65|ed25519+ml-dsa-65] [-csr <request.pem> [-cn <name>]] [-color auto|always|never]
Creates an approver key pair for bide approve. The private key is written to <key-file> (the key's
seed as hex: 64 characters for ed25519, the default; "ecdsa-p256:" and the 32-byte private
scalar for ECDSA P-256, the scheme most HSMs and cloud KMS sign; "ml-dsa-65:" and the seed for ML-DSA-65;
"ed25519+ml-dsa-65:" and both seeds for a hybrid, for buyers who require post-quantum or hybrid
signatures) with mode 0600, and is never printed; the public key is written to <key-file>.pub and
printed, in the form approval policies and verifiers read:
<scheme>:<hex> e.g. ed25519:<hex>
An ML-DSA-65 or hybrid public key is long (nearly 4000 hex characters). ML-DSA needs a Go
build with crypto/mldsa, which the FIPS 140-3 module v1.0.0 lacks.
Enroll that public key as the approver's verifier in the application that runs the gated agent
(audit.ParsePublicKey reads it), and in the JSON object bide approve -approver-keys and bide view
-approver-keys read: {"ops": "<scheme>:<hex>"}. With -as, bide keygen prints that JSON entry for
the id.
With -csr, bide keygen also writes a PKCS#10 certificate signing request for the new key (Ed25519
or ECDSA P-256 only) to the file, as PEM. It proves possession of the key and names nothing: the
subject is empty (unless -cn) and there are no extensions, so the CA or identity provider sets the name (SAN)
and the key usage. Send it to the CA that issues the approver's certificate; the issued chain is
what bide approve -cert reads. For a key in an HSM or a KMS, bide-hsm csr makes the request.
With -cn <name>, the subject is one common name (printable ASCII text, at most 64 characters). The
gate reads no subject, so the name changes nothing about who may approve; it exists because step ca
sign refuses a request with an empty subject. Without -cn the subject stays empty.
It refuses to overwrite a file (the key, its .pub or the request). The private key file is not encrypted; keep it on the approver's
own machine, readable only by the approver. Anyone who can read it can sign as the approver.
Flags:
-alg string
signature scheme: ed25519, ecdsa-p256, ml-dsa-65 or ed25519+ml-dsa-65 (hybrid) (default "ed25519")
-as string
the approver id the key is for: prints the approver-keys entry for it
-cn string
with -csr: make the request's subject this one common name (printable ASCII, at most 64 characters). The gate ignores the subject; step ca sign needs one
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-csr string
also write a certificate signing request for the new key to this PEM file (ed25519 or ecdsa-p256; no SAN or usage in it, the CA sets them). It must not exist
-out string
file to write the private key to (mode 0600); the public key goes to <file>.pub. It must not exist
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide migrate
Create or check a Postgres journal's schema as its owner, so the service needs no DDL rights.
usage: bide migrate -postgres-env <var> -schema <name> [-prefix <p>] [-dry-run]
Creates or checks a Postgres journal's schema, as the role in the DSN, so that the running service
can open the store with postgres.WithoutMigration under a role that has no DDL rights. Run it
with the schema's owner at deploy time, and again after upgrading bide.
It creates the tables (bide_steps, bide_leases, bide_events, bide_schema_version, bide_holds),
the bide_next_seq_v1 and bide_redact_v3 functions and the lease indexes that are missing, and
revokes EXECUTE on every older bide_redact function from PUBLIC and from the roles it was granted
to, and does nothing else: it never alters or drops a table or replaces a function, it is
idempotent, and it refuses a schema newer than this bide's. It reports the schema version before and after ("none" before the first
migration), and what it created. With -dry-run it runs the migration in a transaction and rolls
it back, printing the SQL: that shows what would be created and that the role may create it, and
leaves nothing behind.
The DSN is read from the environment variable -postgres-env names and is never an argument or
output. -schema is required (the schema must exist; the migration does not create it): without one the tables would
land in whichever schema the DSN's search path puts first.
Exit status is 0 when the schema is current, 1 when the migration failed, and 2 for a usage
error.
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-dry-run
run the migration in a transaction, print its SQL, and roll back
-postgres-env string
the environment variable holding the owner role's Postgres DSN (required)
-prefix string
the table name prefix (empty: "bide_")
-schema string
the schema the tables are in; it must exist (required)
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide check
Check plan flow configs, for CI: one file:node: message line per problem.
usage: bide check [-strict] [-blocks <description.json>] <flow.yaml|flow.json>...
bide check <flow.yaml|flow.json> -diff <old config|git revision> [-blocks <description.json> [-old-blocks <description.json>]] [-check [-fail-on-weaken]]
Checks each plan flow config without running it, and prints one "file:node: message" line per
problem ("file:from->to: message" for an edge or arm). The check is structural: types and
registered blocks are checked when a program serves the page with its plan.Registry (package
plan/planview). It is the check bide view -config shows on the graph.
It then prints a taint line, so output is no longer empty for a clean config; the exit status is unchanged. With
-blocks (or a Registry) the line is a taint section: the nodes that may read a declared source of untrusted
content, and what the flow's policy would do to them (escalates, refused, exempt, or "reads untrusted" when the
policy is not given in the description: its "taint_policy"). Without them it is "taint: not known without
-blocks" (or "taint: not known (reason)" when the blocks are given but declare no taint, as a
version 1 description does). It is a may-view of the flow's order and cannot see an undeclared source, a run whose input is declared
untrusted, or the taint of an agent or nested flow a block runs.
With -blocks it also checks them, by name, against a description of the program's registered
blocks (a program writes one with json.Marshal of plan.Registry.Describe): block, predicate and
merge names, the types along every edge, safety, the approval gates the blocks declare in Go, and the
digest. The result is labelled as per the file and not checked against the program: a description can
be stale or wrong, and the check made with the program's own plan.Registry (package plan/planview) is
the control. A block the description holds and the config does not use is not reported. With -diff,
-blocks describes the config; with -diff, -old-blocks describes the earlier version, which without it is checked
structurally (a description is never applied to the other side). Adding a
description never makes -diff less strict: if a side has errors against it, the diff is made structurally,
as without it, and is labelled not certified (-fail-on-weaken fails on it).
A config's assert lines are checked too, by reachability on the declared graph:
every path to <node> passes approval >= K [of N]
every path to <node> passes <node>
every path to a terminal passes <node>
no side effect after <node>
<node> reachable
<node> unreachable
A violated assertion is an error, printed with a shortest counterexample path ("counterexample:
a -> b -> c"); so is an assertion that is not in this grammar, names an undeclared node, or cannot
be decided. A file with assertions ends with a line counting their verdicts.
With -diff it compares the config with an earlier version of it instead, and serves a read-only
local page (like bide view) that draws the new flow with added nodes and edges in green, removed
ones as dashed red ghosts and changed nodes in amber, and calls out a weakened approval policy (a
gate removed, its need lowered, an approver added without raising the need, exclude_principal
dropped, or its timeout removed or lengthened), a node that every path reached through a gate before and some path now reaches without one (whatever its safety), a new effect no gate guards, a lowered safety, a Switch condition changed
beside an ungated effect, a block changed on an ungated effect node (without the Registry), or an assert
line removed, loosened, or kept and no longer holding (violated, undecided, or holding only vacuously). -diff takes a file; when no file has that name, a git revision read with git show: <rev>:<path>
(git's own form), or a bare <rev> for the config's own path at that revision (bide check
flows/refund.yaml -diff main). With -check it serves nothing, prints one line per change and a
summary line, and exits 0: a diff is not a failure, unless -fail-on-weaken finds an approval gate
removed or weakened, or another weakening named above: a side-effecting node that newly reads untrusted data when
the policy is known to be absent, or a node that no longer declares a source ("exposure"; the page says UNTRUSTED
EXPOSURE WIDENED). A node that newly reads untrusted data under a policy that gates or refuses it, or when it is
exempt, is listed as a change. When the taint of the two versions cannot be compared (the policy is not given, or
only one side has -blocks or -old-blocks and it states a source) the diff is labelled not certified and
-fail-on-weaken fails on it; when neither side has -blocks it prints "taint not compared (no -blocks)" (or
"(no -blocks on one side)", or a note that a version 1 description carries no taint declarations) and
certification is unchanged. Flags may follow the file names.
On a terminal the output is colored (a red cross on each error and its counterexample path in red,
a green check on assertions that all hold); piped or redirected it is plain text. -color=never, or
NO_COLOR set to any value, turns color off; -color=always keeps it on.
-addr string
with -diff: address to serve the page on, a loopback IP (127.0.0.1 or ::1) or localhost, with a port (default "127.0.0.1:8484")
-blocks string
a description of the program's registered blocks (json.Marshal of plan.Registry.Describe): check blocks, types, safety and gates by name; labelled as per the file, not checked against the program
-check
with -diff: serve nothing and print each change, then a summary line
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-diff string
compare the one config given with this earlier version: a file, or else a git revision (<rev>:<path>, or <rev> for the config's path at rev)
-fail-on-weaken
with -diff -check: exit 1 if an approval gate was removed or weakened (its need lowered, an approver added without raising the need, exclude_principal dropped, its timeout removed or lengthened, a node newly reachable without a gate or a lowered safety, a Switch condition changed beside an ungated effect, an exposure to untrusted data that nothing covers, a diff whose taint could not be compared, or an assert line removed, loosened, or kept and no longer holding)
-old-blocks string
with -diff: the description for the earlier version; without it the earlier version is checked structurally (-blocks is never applied to it)
-strict
exit 1 on a warning too
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was readbide audit
Produce and verify audit proofs offline.
bide audit: produce and verify audit proof bundles
bide audit [-json] <verb> [flags]
bide audit -version [-json]
prove -journal <file> -sth <file> (-tool <id> | -index <n>) [-out <file>]
build a ProofBundle for one record against a signed tree head
verify -bundle <file> -pubkey <hex|file>
verify a ProofBundle offline (its head must be a journal head of the bundle's run);
if the proven record says when it was written (a single approver's decision, a
resolved halt, a run's end), print that time as the writing process's claim
verify-governance -policy <file> [-digest <hex>] [-checker <astchecker>]
recompute the policy digest and, with -checker, run the external verified
oracle to certify the policy converges
verify-governed-action -action <bundle> -policy-bundle <bundle> -pubkey <hex|file> [-checker <astchecker>]
verify a governed action end to end: both bundles authentic and in the same
signed tree, the action's policy digest links to the anchored policy leaf, the
leaf's bytes hash to that digest, and (with -checker) the policy converges
verify-convergence -cert-bundle <bundle> -policy-bundle <bundle> -pubkey <hex|file> [-checker <astchecker>]
verify an anchored convergence certificate: both bundles authentic and in the same
signed tree, the certificate certifies the anchored policy's digest, the leaf's bytes
hash to that digest, and (with -checker) the external oracle's verdict AGREES with the
certificate's convergence claim, so a certificate that overstates convergence is caught
verify-quorum -name <quorum> -tally <bundle> -vote <bundle> [-vote <bundle>...] -pubkey <hex|file> -k <n> [-commit <bundle>]
verify a governed k-of-n quorum: the tally and every vote bundle authentic, in the
same signed tree and run, and recorded by the quorum named <quorum>; every vote the
tally records disclosed exactly once; the recorded tally recomputes from the disclosed
votes (a forged tally is caught); and votes_for >= k; with -commit, a governed commit
is anchored in the same tree
verify-run -cert <file> -pubkey <hex|file> [-approved <digest>...] [-approved-file <file>] [-checker <astchecker>]
(at least one of -approved and -approved-file; together they form one allowlist)
verify a proof-carrying run certificate: the used-policy set is bound by a signed
used-policy head to this run and its journal tree, and is a subset of the approved
allowlist (only-approved-policies), and every used policy has an anchored, digest-linked convergence certificate
in the run's signed tree (policies-convergence-certified); with -checker, the external
oracle's convergence verdict on each used policy must AGREE with its certificate
verify-evidence -evidence <file> -pubkey <hex|file> [-approved <digest>...] [-approved-file <file>]
verify a portable evidence package offline and print a plain-English report: the
format, seal (a digest of the package, or the whole package for an older v5 package), key, and run binding, then one line per proven action (tool call, step,
grant), plus the run certificate (checked against the given allowlist, required when
the package carries one) and consistency proof if present; a tool call or step whose
record says when it was written (a resolved halt, a run's end) shows that time as the
writing process's claim
verify-approvals -evidence <file> -pubkey <hex|file> -call <tool-use-id|node-key> -need <k>
-approvers <id,id,...> -approver-keys <file> [-approved <digest>...] [-approved-file <file>]
[-decision-time-tolerance <duration>]
verify an m-of-n human approval gate from an evidence package: the request, every
decision the gate read, its recorded tally, and the call's result all verify under the
log key in one signed tree; recounting the decisions with each approver's key (a JSON
object of approver id to public key text, <scheme>:<hex>) against the exact call reproduces the
recorded tally; the gate enforced the expected policy; and at least k approved. Every
proof in the package must verify too, so a package carrying a run certificate needs the
allowlist it is checked against (-approved / -approved-file, as for verify-evidence).
It also prints each counted decision's two times: decided_at, signed by the approver
(their clock), and recorded_at, when it was journaled (the submitter's clock, not
signed), with the gap, and notes a decision signed more than the tolerance (default
5m) after it was recorded or before the run asked for approval, a recorded_at out of
journal order or after the signed head, and a time that is not canonical (printed
quoted); these notes never change the verdict
stops (-trail <file> | -db <file> | -postgres-env <var>) -stop-policy <file> [-stop-root <digest>]
(-sth <file>... -pubkey <hex|file> | -unanchored) [-max-unattested <duration>] [-as-of <time>]
[-sign-head -log-key <file> -head-out <file>]
verify the kill switch's stop trail: each record is read strictly and must verify, under the
policy the deployment pinned (-stop-policy, a JSON policy document with the approvers' public
keys, the setters and lifters, the lift quorum and the deployment ID) and the chain of signed
policy transitions from its root, in the order the trail holds them (a forged or foreign record
is a problem, and a pin the chain does not reach is one too); with signed heads (-sth, from
audit.SignStopTrail or the anchor log of the store that anchors it, each verified) the trail's
first records are exactly what the newest head commits to, so a deleted or reordered record is
found; records after it are not attested, so with no -max-unattested any such tail fails (whoever
can write the trail's store could have deleted the newest records unseen) and -max-unattested
accepts a tail younger than that. With -db or -postgres-env it also compares the trail with
the control run record for record: a record in force without evidence, or a forged record in
the trail, fails; a signed record on the trail that never reached the control run (a crash
between the two writes) is listed as UNAPPLIED, or SUPERSEDED when a later record went on without it, and does not fail; agent.StopControl.ApplyPending applies an unapplied one. It prints each stop and whether it is in force. With -sign-head (a store, -pubkey, -log-key and -head-out
required) it then signs a head over exactly the records it verified and appends it, as one JSON line,
to -head-out, which -sth reads back: the job to run on a schedule, since the audit fails on any record
after the newest signed head. The heads already in -head-out are verified with the trail, so a
shrunken or rewritten trail is refused, and with nothing new nothing is signed
notifications (-trail <file>... [-journal <file>...] | -db <file> | -postgres-env <var>) [-run <id>]
(-sth <file>... -pubkey <hex|file> | -unanchored) [-max-ack <duration>] [-max-unattested <duration>]
[-strict] [-routing <file>] [-as-of <time>]
verify that every event that needed a person (an unknown-outcome halt, an approval gate,
an aborted run, a recovery failure, an overdue notice, an all-clear) was notified, and
when it was acknowledged: each trail's leaves are read strictly (an unknown record kind or
field is an error) and must be a history a notifier writes (nothing acknowledged twice,
nothing out of order, every acknowledgement after a claim); with signed heads (-sth, from
audit.SignNotifyTrail or the anchor log of a notifier that anchors its trail, any
number per trail, each verified) the trail's first records are exactly what the newest
head commits to, so a deleted or reordered record is found, and the records after it
are reported with how many there are and how long the oldest has gone unattested
(-max-unattested fails a gap older than that, and bounds the tail an event may rest on); and each gate, halt and abort a
journal shows must be observed in its run's trail. Each event gets a verdict: acked,
acked_late (past its deadline or -max-ack), pending, failing, overdue, cleared before
notification, never_notified, and the command fails (exit 1) on acked_late, overdue and
never_notified (and, with -strict, on the warnings unobserved_resolved and all_clear_untimed). A verdict that rests on records after the newest signed head is unattested and fails unless every tail record it rests on is within -max-unattested (default 0: strict; records within a nonzero bound are accepted without a signature); with -routing (the notifier's routing, agent.RoutingOf as JSON), an event with no delivery to a receiver it routes to, or a due escalation step with none, is no_delivery and fails. -db and -postgres-env (a variable holding the DSN) read every run, or -run,
from a store, in the full bide command; the audit-only build reads exported files
caps (-db <file> | -postgres-env <var>) (-sth <file>... -pubkey <hex|file> | -unanchored)
[-namespace <ns>] [-rule <name>] [-window <id>] [-run <id>]
audit the amount-cap ledgers of a store (read-only; the full bide command only). Each ledger run
(@cap/...) must read under the ledger's own rules (dense slots, the cum_after chain, release
references, the over flag, one currency), and its window total, the sum of its live reserves,
must be its last cum_after; the over-limit slots counted under a waiver are listed. Each slot
is compared with the cap-reserve record the run that made the call holds: a record whose slot
is missing is DELETED, one whose cum_after or attempt differs is CHANGED, a reserve slot with no
record is UNRECORDED (a failure when the run has ended; a warning when it has not, since a reservation
interrupted before its record looks the same). A release of a call whose run holds a result the tool
produced is RELEASE_OF_A_CALL_THAT_RAN, since only a call that never began is released; any
other release must be explained by the loop's cap-release record or by the attempt's void
(RELEASE_UNCONFIRMED): without either it fails when anchored and warns when not. Every reserve slot's attempt must have exactly one cap-intent, which sends it to this
ledger with this amount, currency and marking (a planted intent with another window is
INTENT_MISMATCH), and whose window the rule's index run holds and fits its call's own time (the window of the attempt
marker's time or the next one; for an attempt with no marker, not before the run's start:
INTENT_WINDOW); an intent with
no slot is listed, not failed. With signed heads the cap-intent and cap-reserve records of each
run must also lie inside a signed head of that run (RUN_NOT_ATTESTED). With signed heads (-sth, each verified, from the anchor log of the AuditedStore that
anchors the store) a ledger run must be the one the newest head signs, and entries after it are
NOT ATTESTED and fail; with -unanchored the report says first that whoever can write the store
can delete a slot or append a release undetected, and that the audit only finds
inconsistencies it can see. It also reports, without failing, the reconcile exposure: the
slots still counted for attempts the journal records as never started. The filters narrow the
audit, and the report lists what they left unchecked; a filter that matches no ledger is
exit 4, not a pass
redactions (-trail <file> | -trail-db <file> | -trail-postgres-env <var> | -db <file> | -postgres-env <var>)
[-journal <file>...] [-run <id>] -deployment <name> -pubkey <hex|file> [-sth <file>... | -unanchored]
verify the redaction trail (the signed, append-only record of each erasure of journal
content, written by audit.RedactJournal): its signed heads commit to its records, so a
deleted or changed record is TRAIL_ALTERED; a record with no signature that verifies under -pubkey (the
redaction key: planted by someone who can append to the event store) is BAD_SIGNATURE, whatever head covers it, and accounts for nothing (neither does a record
that does not read, MALFORMED); a record signed for another position or after another
record (a replayed, copied or reordered one, which would hide an unfinished pass) is
REORDERED, and one signed for another -deployment (required) is BAD_SIGNATURE (an operator's
signed acknowledgement of exactly that leaf, bide journal acknowledge, turns these findings for it into a note); each begin has an end (INCOMPLETE is an
unfinished pass, finished by running the same plan again); a tombstone in a journal that no
trail record names is UNACCOUNTED (an erasure made by hand), and one whose name or leaf hash
is not what the trail recorded is NAME_MISMATCH or HASH_MISMATCH: a tombstone's name is
outside the journal's hashes, so the signed trail is what attests it; a record the trail lists as
erased that still holds content is NOT_ERASED; a tombstone not stamped at the time of a pass
that listed it is TIME_MISMATCH; a run the trail names with no journal given is UNCHECKED (a
trail checked against no journal checked nothing); a redaction that ran without a covering
signed journal head is UNCOVERED, and one that left the run's events in the event store is EVENT_COPIES_KEPT; a pass that began under a
legal hold the trail shows over the run is REDACTED_UNDER_HOLD; the holds in force by the trail are
listed and, against a database, compared with its holds (HOLD_NOT_IN_STORE: lifted by hand,
HOLD_NOT_IN_TRAIL: placed by hand, HOLD_DIFFERS), and a lift or placement the trail does not match
is HOLD_UNMATCHED. A lift's embedded second-person authorization is checked (a bad signature,
another hold or placement, expired at the lift, or the lifter's own key is LIFT_UNAUTHORIZED), with
-authorizer-pubkey also against the keys given, and -require-lift-authorization makes one mandatory.
For a run whose end marker was erased and which the trail accounts for, the report says how it
ended, per the trail (the journal says only that the run is over). A pass is judged by its last record, so a failed pass that
the same plan later finished is a note, not a finding. -db and -postgres-env read every run's
journal (and the trail, unless -trail-db or -trail-postgres-env name the store it is kept in
apart from the journal) from a store, in the full bide command; the audit-only build reads
exported files
verify-receipts -receipt <file|dir> -journal <export> -heads <file> -pubkey <hex|file> -approver-keys <file>
verify decision receipts (written by bide approve): each signature verifies for the
approver's key over the exact call, and the signed tree heads (-heads: a head, or one per
line, as the anchor log holds them) commit to the decision where the receipt says it was
journaled. Distinct verdicts: anchored (PASS); redacted (anchored), a redaction replaced the
record with a tombstone that keeps its leaf hash (PASS); pending, the journal holds it and
no head reaches it yet (INFO, exit 0); "receipt not matched by the journal (the approver's
claim)", the journal does not hold the decision where the receipt says: a receipt carries no
evidence the application ever journaled it, so this proves a deletion only if the receipt
is trusted; "decision deleted after signing", only for a receipt that carries an anchoring
proof (the decision's record under a signed head), when a signed head that matches the
journal commits to something else at its position; unchecked, a head reaches it but does
not match the journal given, or the proof does not hold. -update stores the anchoring
proof in each receipt file whose decision a signed head now commits to. -receipt,
-journal and -heads repeat
verify-decision-coverage -journal <file> -heads <file> [-heads <file>...] -pubkey <hex|file>
[-max-records <n>] [-max-age <duration>] [-max-age-tolerance <duration>] [-max-unanchored <duration>] [-now <time>]
check that every approval decision in a journal export is covered by a signed tree head
(the operator's or auditor's check, which needs no receipts; the approver runs
verify-receipts to check their own decisions were kept; both read heads the same way and
classify them by one rule, -heads taking a head or one per line):
a decision written by a process that does not sign (a CLI writing the database) is under
no head until the signer next writes to the run, which for a rejection may be never. A
head counts only if it verifies under the key, is a journal head of the export's run, and
is the root of the export's own prefix of its size; heads are used by size, in any order.
Each decision is covered, pending, or overdue. Overdue is: -max-records records of
journal after it with no head covering it (positions and head sizes, no clock), or, with
-max-age, recorded more than that plus -max-age-tolerance before -now (default: this
machine's clock; the weaker basis, since the recorder's clock is its own). With neither
bound nothing is overdue; under -max-age a decision with no recorded time (an unsigned
agent.Approve decision records none) counts as over it, and with a bound set a journal whose decisions no counted head covers at all (a wrong -pubkey) fails, with a WARNING. A head the log key signed for this
run that does not match the export (the export is shorter than the head, or its prefix
differs) is divergent, which fails the verb like an overdue decision: a decision deleted
from an export looks exactly like that, so re-export the journal and run again. Covered
means in a signed head, not authentic (verify-approvals checks that). Halt resolutions are
not checked. The records after the newest counted head are always listed (positions, and
when that head was signed); with -max-unanchored the verb fails when the newest head is older
than that and records follow it, which separates a head held back by a minimum interval
between heads from a failed publish
prove-absent -journal <file> -sth <file> -key (tool:<id>|policy:<digest>) [-out <file>]
prove a thing did NOT happen (no such tool call / no action under that policy)
against a signed key-set head of the matching kind (see audit.SignAbsenceRoot)
verify-absent -bundle <file> -pubkey <hex|file>
verify an absence proof offline against a head of the key's own key set
Export a journal for `prove` and `prove-absent` with audit.ExportJournal(ctx, store, runID),
marshaled to JSON (format bide.audit.journal-export.v1: each record's stored bytes, verbatim). Every
JSON input is parsed strictly: a duplicate or case-variant key, an unknown field, or invalid UTF-8 is
an error; a bundle, certificate, package, journal export or signed tree head (at any depth) must
carry the "format" this version reads (one made by an older release is refused with a message
naming the format; -version lists them); and a public key is <scheme>:<hex>, where the scheme is
ed25519, ecdsa-p256, ml-dsa-65 or ed25519+ml-dsa-65, or bare 64-digit ed25519 hex. The key's scheme must be the
scheme the artifact is signed under. Every verb takes -max-input-bytes <n>: an input file larger
than n bytes (default 268435456, 256 MiB) is an error, and none is read past the cap. Every signed
tree head an input carries must have a positive timestamp (Unix nanoseconds) no later than this
machine's clock plus -max-clock-skew <duration> (default 5m). Every verb takes -json: it prints one
JSON report on stdout (exit_code, result, verified, output, errors) instead of the text report. On a
terminal the text report is colored, with a VERIFIED or FAILED banner at its end; -color=never or
NO_COLOR turns that off, and a pipe, a file or -json is always plain.
Exit status. Only 0 means verified; treat every other status as a failure, and 4 as a failure,
never as a reason to retry (a tampered "format" field yields 4):
0 verified (for prove and prove-absent: the artifact was written)
1 read and understood, and not verified
2 usage error: a bad flag or argument; nothing was read
3 no verdict: the -checker gave none (it could not be started, exited with a status other
than 0 or 1, was killed, or printed an unreadable compensation_free line), or an internal error
4 an input is unreadable or unusable: a missing or unreadable file, one over -max-input-bytes,
JSON that does not read strictly, an unknown or unsupported format, or an artifact of the
wrong type for its flag
When several apply, 1 wins over 4, and 4 over 3: a verb reads every input and runs every check
that does not depend on an unusable one, so a tampered input is reported as 1 even beside an
unreadable one.
Exit status:
0 verified (for prove and prove-absent: the artifact was written)
1 read and understood, and not verified
2 usage error: a bad flag or argument; nothing was read
3 no verdict: the -checker gave none, or an internal error
4 an input is unreadable or unusablebide audit caps
Usage of bide audit caps:
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-db string
read the ledgers and the runs from this SQLite journal (opened read-only)
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-namespace string
only the ledgers of this cap namespace (agent.WithCapNamespace)
-postgres-env string
read them from the Postgres journal whose DSN is in this environment variable (never given on the command line)
-pubkey string
the public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it; it verifies every -sth
-rule string
only the ledgers of this cap rule
-run string
only the calls of this run and its sub-runs: their slots and cap-reserve records, and the ledgers that hold them; the other ledgers and runs are not checked, and the report says so
-sth value
a signed tree head over a ledger run, as JSON (an entry's sth from the anchor log of the AuditedStore that anchors the store; a file may hold the heads of many runs, one JSON value after another); repeat for as many as you have: each must verify and match a prefix of its ledger, the largest is the newest
-unanchored
read the ledgers with no signed head: whoever can write the store can delete a slot or append a release undetected, and this audit only finds inconsistencies it can see
-window string
only the ledgers of this window (a day 2006-01-02, an hour 2006-01-02T15, or a root run's ID)bide audit notifications
Usage of bide audit notifications:
-as-of string
judge pending events as of this RFC 3339 time (default now)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-db string
read the trails and journals from this SQLite journal (opened read-only) instead of from files
-grace duration
how long after an event began that a missing observation is not yet a failure (the notifier's detection window) (default 5m0s)
-journal value
a run's journal export (audit.ExportJournal as JSON) to cross-check against; repeat once per run
-json
print one JSON report on stdout instead of the text report
-max-ack duration
fail an event not acknowledged within this long of when the run entered its state (0: only each event's recorded deadline)
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-max-unattested duration
how long records after a trail's newest signed head may stay unattested: a trail with one older fails, and an event resting on tail records no older than this is accepted WITHOUT a signature, so its content and times (written by whoever appended it) are trusted; 0 (default): strict, an event resting on the tail fails (unattested)
-postgres-env string
read them from the Postgres journal whose DSN is in this environment variable (never given on the command line)
-pubkey string
the public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it; it verifies every -sth
-recovery-failing-after duration
how long a recovery failure episode may be open before a recovery_failing event is owed (the notifier's setting) (default 15m0s)
-routing string
the notifier's routing as JSON (agent.RoutingOf, from the options the notifier was built with): every event must have been delivered to the receivers it routes to, and each due escalation step to its receiver; without it per-receiver completeness is not checked
-run string
with -db or -postgres-env: only this run and its sub-runs; default every run (the kill switch's stops belong to no run and are checked only when the audit is of every run)
-sth value
a signed tree head over a trail, as JSON (audit.SignNotifyTrail, or an entry's sth from the anchor log of a notifier that anchors its trail); repeat for as many as you have, any number per trail: each must verify and match a prefix of the trail, the largest is the newest
-stop-policy string
with -db or -postgres-env: the kill switch's stop policy (the JSON bide stop -stop-policy reads), so the control run's stops are judged as an audited deployment judges them; without it they are read as a basic deployment's, and a control run holding signed records is refused. Every stop in force must have been notified (stop_set), and every lift of one (stop_lifted)
-stop-root string
with -stop-policy: the digest of the deployment's root policy, when the file is a later policy the chain reaches
-stops-within duration
with -db or -postgres-env: how far back a stop that is over is still owed its events (the notifier's WithNotifyStopsWithin; a stop in force is always owed, and one set and lifted longer ago is history) (default 168h0m0s)
-strict
also fail (exit 1) on a warning: a decided gate no notifier observed (unobserved_resolved), or an all-clear owed that cannot be timed (all_clear_untimed)
-trail value
a notification trail export (audit.ExportNotifyTrail as JSON); repeat once per trail
-unanchored
accept a trail with no signed head: it is read, and nothing attests that it is complete or unalteredbide audit prove
Usage of bide audit prove:
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-index int
prove the record at this journal index (default -1)
-journal string
path to the journal export JSON (audit.ExportJournal)
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-out string
write the bundle here (default: stdout)
-sth string
path to the signed tree head JSON
-tool string
prove the tool call with this ToolUseIDbide audit prove-absent
Usage of bide audit prove-absent:
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-journal string
path to the journal export JSON (audit.ExportJournal)
-json
print one JSON report on stdout instead of the text report
-key string
what to prove absent: tool:<id> or policy:<digest>
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-out string
write the absence bundle here (default: stdout)
-sth string
path to the signed absence tree head JSON (see audit.SignAbsenceRoot)bide audit redactions
Usage of bide audit redactions:
-authorizer-pubkey value
the public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it of a key a legal hold lift's authorization (bide journal hold authorize) must be signed by; repeat. A lift's embedded authorization is checked either way; with these keys it must also be signed by one of them
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-db string
read the trail and the journals from this SQLite journal (opened read-only) instead of from files
-deployment string
the deployment name every trail record must be signed for (required; RedactionOptions.Deployment): a record copied from another deployment's trail under the same key is BAD_SIGNATURE
-journal value
a run's journal export (audit.ExportJournal as JSON) to check the tombstones of; repeat once per run
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-postgres-env string
read them from the Postgres journal whose DSN is in this environment variable (never given on the command line)
-pubkey string
the public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it; it verifies every -sth
-require-lift-authorization
every legal hold lift needs a valid second-person authorization: one with none is LIFT_UNAUTHORIZED (needs -authorizer-pubkey)
-run string
with -db or -postgres-env: only this run and its sub-runs; default every run
-sth value
a signed tree head over the redaction trail, as JSON; repeat for as many as you have: each must verify and match a prefix of the trail
-trail string
the redaction trail export (audit.ExportNotifyTrail of redact:@log, as JSON)
-trail-db string
read the redaction trail from this SQLite file (opened read-only), when it is kept apart from the journal; the journals then come from -db or -postgres-env, or -journal
-trail-postgres-env string
read the redaction trail from the Postgres database whose DSN is in this environment variable (never given on the command line)
-unanchored
accept a trail with no signed head: it is read, and nothing attests that it is complete or unalteredbide audit stops
Usage of bide audit stops:
-as-of string
judge the heads and the tail as of this RFC 3339 time (default now)
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-db string
read the trail and the control run from this SQLite database (opened read-only) instead of from a file
-head-out string
with -sign-head: the file the signed head is appended to (created if absent); it is verified first, so a trail that shrank or was rewritten since an earlier head is refused, not re-signed
-json
print one JSON report on stdout instead of the text report
-log-key string
with -sign-head: the private key file that signs the head (as bide keygen writes it; on Unix not readable by group or others). It is the deployment's log key, not an approver's: -pubkey names its public half
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-max-unattested duration
accept records after the newest signed head for this long: a tail older than that fails, and with 0 (default) any unattested tail fails, since whoever can write the trail's store could have deleted the newest records unseen
-postgres-env string
read them from the Postgres database whose DSN is in this environment variable (never given on the command line)
-pubkey string
the public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it; it verifies every -sth
-sign-head
after verifying the trail against the control run (-db or -postgres-env, required), sign a head over exactly the verified records with -log-key and append it, as one JSON line, to -head-out; the heads in that file are read back by -sth. Run it on a schedule: with no -max-unattested the audit fails on any record after the newest signed head
-sth value
a signed tree head over the trail, as JSON (audit.SignStopTrail, or an entry's sth from the anchor log of the store that anchors it); repeat for as many as you have: each must verify and match a prefix of the trail, the largest is the newest
-stop-policy string
the stop policy the deployment pinned, as a JSON document (agent.StopPolicyDoc): the approvers' public keys, the setters and lifters, the lift quorum and the deployment ID; every record must verify under it and the chain of policy transitions from its root
-stop-root string
the digest (agent.StopPolicy.Digest) of the deployment's root policy, when -stop-policy is a later one the chain reaches; default the pinned policy itself
-trail string
a stop trail export (audit.ExportStopTrail as JSON)
-unanchored
accept a trail with no signed head: it is read, and nothing attests that it is complete or unalteredbide audit verify
Usage of bide audit verify:
-bundle string
path to the ProofBundle JSON
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-absent
Usage of bide audit verify-absent:
-bundle string
path to the AbsenceBundle JSON
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-approvals
Usage of bide audit verify-approvals:
-approved value
an approved policy digest for the package's run certificate; repeat once per allowed policy
-approved-file string
path to a file of approved policy digests, one per line
-approver-keys string
JSON object of approver id to public key text (<scheme>:<hex>, or bare ed25519 hex), e.g. {"ops":"ed25519:ab12..."} or {"ops":"ecdsa-p256:04ab..."}
-approvers string
the policy's eligible approver ids, comma-separated, in policy order
-call string
the gated call's tool-use id, or a gated plan flow node's key ("node:<name>", "node:iter:<n>:<name>")
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-decision-time-tolerance duration
how far a decision's signed time may be after the time bide recorded it before it is noted (a note, never a failure) (default 5m0s)
-evidence string
path to the EvidencePackage JSON carrying the approval evidence
-exclude-principal
the policy excludes the run's requesters (its principal and those of the runs above it) from approving (separation of duties); the evidence must prove the run's run:principal
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-need int
approvals the policy requires (k)
-pubkey string
the log's public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it
-separate-approvers
the policy is the escalation gate of a taint policy that separates approvers (-call is the instance, "<call>#taint" or "node:<name>:taint"): the approvers the call's or node's own gate counted do not count here; the evidence must prove that gate's tallybide audit verify-convergence
Usage of bide audit verify-convergence:
-cert-bundle string
path to the convergence-leaf ProofBundle JSON (from ProveConvergence)
-checker string
path to the external verified oracle (astchecker); if set, its verdict must agree with the certificate
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-policy-bundle string
path to the policy-leaf ProofBundle JSON (from ProvePolicy)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-decision-coverage
Usage of bide audit verify-decision-coverage:
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-heads value
path to a signed tree head: one head, or one per line as the anchor log holds them; repeat (any order), as for verify-receipts
-journal string
path to the journal export JSON (audit.ExportJournal)
-json
print one JSON report on stdout instead of the text report
-max-age duration
how long after its recorded_at a decision may stay uncovered (0: no bound); compares clocks
-max-age-tolerance duration
clock skew allowed on top of -max-age (default 5m0s)
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-max-records int
records the journal may hold after a decision before a head must cover it (0: no bound)
-max-unanchored duration
how long the journal's last records may stay under no signed head: fail when the newest counted head was signed longer ago than this and records follow it (0: report the tail, never fail on it); a tail within it is a head held back by a minimum interval between heads, an older one a likely failed publish
-now string
the time -max-age and -max-unanchored are measured to, RFC 3339 (default: this machine's clock)
-pubkey string
the log's public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-evidence
Usage of bide audit verify-evidence:
-approved value
an approved policy digest for the run certificate; repeat once per allowed policy
-approved-file string
path to a file of approved policy digests, one per line
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-evidence string
path to the EvidencePackage JSON (from audit.Evidence)
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-governance
Usage of bide audit verify-governance:
-checker string
path to the external verified oracle (astchecker); if set, it is run on the policy
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-digest string
expected policy digest as hex (e.g. from a ProofBundle or the anchor); must match if set
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-policy string
path to the serialized combinator policy (gsm PolicyBytes / WriteMachineAST output)bide audit verify-governed-action
Usage of bide audit verify-governed-action:
-action string
path to the action ProofBundle JSON (from prove -tool)
-checker string
path to the external verified oracle (astchecker); if set, it certifies the policy converges
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-policy-bundle string
path to the policy-leaf ProofBundle JSON (from ProvePolicy)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide audit verify-quorum
Usage of bide audit verify-quorum:
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-commit string
path to the commit action ProofBundle JSON (optional)
-json
print one JSON report on stdout instead of the text report
-k int
the quorum threshold to assert: votes_for must be >= k
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-name string
the quorum's name, as passed to govern.Quorum
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it
-tally string
path to the quorum tally ProofBundle JSON (the quorum/<name>/tally step)
-vote value
path to one vote ProofBundle JSON (a quorum/<name>/vote/<voter> step); repeat once per voterbide audit verify-receipts
Usage of bide audit verify-receipts:
-approver-keys string
JSON object of approver id to public key text (<scheme>:<hex>), e.g. {"ops":"ed25519:ab12..."}
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-heads value
signed tree heads of the journal: a file with one head, or one head per line (the anchor log a published head is appended to); repeatable
-identity-policy string
the certificate policy file (trust anchors, pinned intermediates, the approver-to-identity map; see docs/guides/hitl-approval.md): required for a certificate-bound receipt, which is checked against it and the log key instead of -approver-keys. The check is the identity at the time the decision became provable; revocation status is not checked
-journal value
the run's journal export (audit.ExportJournal), one per run the receipts name; repeatable
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-pubkey string
the log's public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing it
-receipt value
a decision receipt file, or a directory of *.receipt.json files; repeatable
-update
write an anchoring proof into each receipt whose decision a signed head now commits to (an atomic rewrite of the receipt file, mode kept): from then on a signed head that omits the decision proves its deletion; without it the verdict is the approver's claimbide audit verify-run
Usage of bide audit verify-run:
-approved value
an approved policy digest; repeat once per allowed policy
-approved-file string
path to a file of approved policy digests, one per line
-cert string
path to the RunCertificate JSON (from audit.CertifyRun)
-checker string
path to the external verified oracle (astchecker); if set, its verdict must agree with each policy's certificate
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never; -json is never colored
-json
print one JSON report on stdout instead of the text report
-max-clock-skew duration
how far past this machine's clock a signed head's timestamp may be (default 5m0s)
-max-input-bytes int
the largest input file, in bytes, the verb reads; a larger one is an error (default 268435456)
-pubkey string
public key as <scheme>:<hex> (ed25519, ecdsa-p256, ml-dsa-65, ed25519+ml-dsa-65) or bare ed25519 hex, or a path to a file containing itbide version
Print the version and the artifact formats bide audit reads (-json for JSON).
usage: bide version [-json] [-color auto|always|never]
-color when
when to color the output: auto (the default: on a terminal, unless NO_COLOR is set or TERM is dumb), always or never
-json
print the version and the artifact formats as JSON
Exit status:
0 success
1 failure: an input cannot be read or the command failed; for check, an error was found
(with -strict, any problem)
2 usage error: a bad flag or argument; nothing was read