Skip to content

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

CommandWhat it does
bide initscaffold a project: a gated plan flow on SQLite (or, with -agent, an agent with a taint policy), with evidence for bide audit
bide demokill an agent mid-payment and watch it not charge twice (no API key)
bide doctorcheck that a first run can work: Go, SQLite, the module cache, model keys, your project
bide samplewrite a sample journal of varied runs, with evidence and flow configs, and open bide view on it
bide themecheck a theme file for the run viewer and the editor against the contrast and distinctness rules
bide viewa read-only local page for one run of a journal, or a flow config's graph
bide edita local page for a flow config: the graph, the approval gates, the assertions, and what an edit weakens; edit the source and save
bide notifyset up and test the webhook notifier: test a receiver, run a local one, relay to Slack and PagerDuty
bide journalerase personal data from finished runs of a journal, accountably: a dry-run plan, then a signed record of each erasure
bide approverecord your signed approval (or -reject) of a call that waits for a decision; -list shows what waits
bide stopstop 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 identitypre-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 keygencreate an approver key pair for bide approve and print the public key policies and verifiers use
bide migratecreate or check a Postgres journal's schema as its owner, so the service needs no DDL rights
bide checkcheck plan flow configs, for CI: one file:node: message line per problem
bide auditproduce and verify audit proofs offline
bide versionprint 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.

text
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 read

bide demo ​

Kill an agent mid-payment and watch it not charge twice (no API key).

text
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 read

bide doctor ​

Check that a first run can work: Go, SQLite, the module cache, model keys, your project.

text
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 read

bide sample ​

Write a sample journal of varied runs, with evidence and flow configs, and open bide view on it.

text
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 read

bide theme ​

Check a theme file for the run viewer and the editor against the contrast and distinctness rules.

text
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 read

bide view ​

A read-only local page for one run of a journal, or a flow config's graph.

text
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 read

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.

text
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 read

bide notify ​

Set up and test the webhook notifier: test a receiver, run a local one, relay to Slack and PagerDuty.

text
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 read

bide notify test ​

text
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 does

bide notify listen ​

text
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-env

bide notify relay ​

text
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.url

bide journal ​

Erase personal data from finished runs of a journal, accountably: a dry-run plan, then a signed record of each erasure.

text
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 read

bide journal redact ​

text
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's

bide journal acknowledge ​

text
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 trail

bide journal hold ​

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

text
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 read

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.

text
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 nothing

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.

text
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 ready

bide identity fetch-crl ​

text
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 ​

text
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 ​

text
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 mark

bide identity ack-reset ​

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

text
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 read

bide migrate ​

Create or check a Postgres journal's schema as its owner, so the service needs no DDL rights.

text
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 read

bide check ​

Check plan flow configs, for CI: one file:node: message line per problem.

text
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 read

bide audit ​

Produce and verify audit proofs offline.

text
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 unusable

bide audit caps ​

text
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 ​

text
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 unaltered

bide audit prove ​

text
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 ToolUseID

bide audit prove-absent ​

text
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 ​

text
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 unaltered

bide audit stops ​

text
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 unaltered

bide audit verify ​

text
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 it

bide audit verify-absent ​

text
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 it

bide audit verify-approvals ​

text
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 tally

bide audit verify-convergence ​

text
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 it

bide audit verify-decision-coverage ​

text
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 it

bide audit verify-evidence ​

text
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 it

bide audit verify-governance ​

text
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 ​

text
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 it

bide audit verify-quorum ​

text
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 voter

bide audit verify-receipts ​

text
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 claim

bide audit verify-run ​

text
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 it

bide version ​

Print the version and the artifact formats bide audit reads (-json for JSON).

text
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

Apache-2.0 licensed.