Command line
Two commands, one per package. Both run on plain Node 22 or later. Exit code 0 on success, 1 when a check or an operation fails, 2 for usage errors. Everything diagnostic goes to stderr; stdout carries the result, so --json output can be piped.
agent-custody
| command | what it does | page |
|---|---|---|
keygen --dir <dir> --name <name> | an Ed25519 key pair as <name>.key and <name>.pub; prints the keyid | SDK |
grant --key <principal.key> --principal <id> --agent <id> --scopes <a,b> [--ttl-hours 24] [--agent-key <agent.pub>] --out <file> | a signed delegation | gateway |
delegate --key <agent.key> --parent <grant.json> --agent <sub> --scopes <a,b> [--ttl-hours N] [--agent-key <sub.pub>] --out <file> | a narrower grant for a sub-agent | gateway |
console --config <gateway.json> [--port 8795] [--host 127.0.0.1] [--token-env CONSOLE_TOKEN] [--gateway-url <url>] [--state-dir <dir>] | the admin console for a gateway, a separate service behind a token read from the environment: its config and tools, the config check, receipts with a verdict each, a policy editor that validates and replays recorded calls before it saves, grant inspection and revocation, and an audit trail. It holds no principal key and never signs | console |
check --config <gateway.json | door.json | egress.json> [--connect] [--json] | what the gateway, the door, or the egress witness would fail on at startup, found before it starts: the config (and unknown keys), the keys, the Cedar policy, the grant, the credential variables, stdio commands, and writable paths. For an egress config: unknown keys, the key, each agent's secret variable and the log, Splunk, and OTel variables, the log.keys files, the Cedar or Rego policy, exactly one of logFile and log, and a warning on observe mode. --connect also starts the upstreams, catches tool-name collisions and unreachable servers, and checks every tool name the config and grant mention against the tools offered. Exits 1 on an error | configuration |
revoke --config <gateway.json> --grant <grant.json> | appends the grant's digest to the config's revokedGrants file, by rename; a running gateway refuses it, and every grant delegated from it, on the next call | gateway |
reconcile --config <gateway.json> --operation <uuid> | reads the provider's operation record; commits a linked reconciliation receipt before closing a financial reservation; prints { operation, status, receipt } | gateway |
policy simulate --policy <proposed.cedar> --receipts <dir> --issuer-key <pub>… [--principal-key <pub>]… [--approval-key <pub>]… [--log-key <pub>]… [--capture-key-env NAME] [--disclose <file>]… [--json] [--out <report.json>] | verifies local receipt bundles, one at a time (a receipt whose id does not match its file name fails the command), and replays their recorded calls against the proposed policy; groups changed decisions by tool and reason with receipt ids, records the proposed policy digest; a call with only an authorization file, or with withheld inputs that the key or disclosures do not open, is skipped and the replay exits 1 | policies |
completeness --receipts <dir> --issuer-key <pub>… [--principal-key <pub>]… [--log-key <pub>]… [--log <log.jsonl>] [--log-id <id>] --provider stripe --object refunds|payouts|transfers --key-env NAME --tool <name>… --since <ISO> --until <ISO> [--id-path id] [--amount-field amount] [--currency-field currency] [--beneficiary <arg>=<field>]… [--json] | for an auditor: the provider's objects in a window matched against verified receipts; exits 1 unless complete | completeness |
gateway --config <gateway.json> [--http [--port 8790] [--host 127.0.0.1] [--idle-minutes 30]] | the gateway over stdio, or shared over HTTP | gateway |
gateway --config <gateway.json> --a2a [--port 8790] [--host 127.0.0.1] | the gateway as an A2A agent in front of the config's one a2a upstream | gateway |
egress --config <egress.json> [--port 8791] [--host 127.0.0.1] | the egress witness: a forward proxy (CONNECT and plain HTTP, no TLS interception) for a locked-down agent's calls around the gateway; each agent proves itself with its own Proxy-Authorization, the Cedar or Rego policy decides per host:port, every connection is receipted; GET /.well-known/agent-custody-egress | egress |
egress draft-policy --receipts <dir> --issuer-key <witness.pub>... [--log-key <pub>]... [--log <log.jsonl>] | a first egress policy from observe-mode receipts: reads only regular files, never through a symlink; verifies each receipt and skips (naming on stderr) any that does not verify; one permit per verified agent and scheme (connect or http, named in the rule) over the host:port destinations the witness relayed for it, sorted and de-duplicated, each with its count and first and last time. The output starts with a warning that it permits whatever the agents did, bad destinations included, and must be reviewed. Exits 1 when nothing is left to permit. Guide | |
acs --config <acs.json> | an OWASP ACS Guardian, one document at a time: reads a JSON-RPC steps/toolCallRequest or steps/toolCallResult (or a batch) on stdin, prints the allow or deny answer with the receipt in policy_data["agent-custody"], and writes a signed receipt for each decision; see the ACS Guardian | |
door --config <door.json> [--port 8780] [--host 127.0.0.1] | a receipted reverse proxy in front of your own site or API: every arrival classified, decided by policy per route, relayed or refused, receipted; GET /.well-known/agent-custody-door | door |
init claude-code [--dir <dir>] [--user] [--enforce] [--log-url <url> --log-key <pub> [--log-id <id>] [--log-token-env NAME]] | sets up custody for your own Claude Code sessions: an agent key, sdk.json in observe mode, a starter deny policy, and the three hooks with absolute paths in .claude/settings.local.json (--user: ~/.claude/settings.json). Merges into existing settings, never overwrites a key, config, policy, or log key, warns when a log flag is not applied, and stops without a change on a settings file that is not valid JSON | Claude Code |
audit-sessions [--since 7d|24h|<date>|all] [--dir <dir>] [--policy <file.cedar>] [--counts] [--json] | a read-only preview of which past Claude Code tool calls a policy would have denied, from the transcripts; writes nothing | Claude Code |
report --config <sdk.json> | verifies the receipts of the config and prints the calls that the policy would have denied: tool, command or path, rule, receipt id. A receipt that does not verify is counted apart and the command exits 1 | Claude Code |
hook [--config <sdk.json>] | the Claude Code hook; the event on stdin | Claude Code |
serve --config <sdk.json> [--port 8788] [--host 127.0.0.1] | the sidecar | sidecar |
verify <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--approval-key <pub>] [--log-key <pub> | --log-url <url>] [--log-id <id>] [--require-strict] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--disclose <file>] [--capture-key-env NAME] [--json] | checks one receipt | verify |
verify-perathos <session.jsonl> [--key <hex>]... [--allow-unsigned] [--head <session.head.json>] [--json] | checks a Perathos session log (perathos.receipt/v1) against its spec and labels it as recorded inside the agent's host; exit 1 when it is not valid | verify |
verify --markdown <dir|bundle.json>… --issuer-key <pub>… [--principal-key <pub>]… [--log-url <url>] [--log-id <id>] | checks every bundle in a directory and prints one Markdown table; the GitHub Action posts it on a pull request | verify |
export --receipts <dir> --out <dir> --issuer-key <pub>… [--principal-key <pub>]… [--approval-key <pub>]… [--since <ISO time>] [--allow-clear] | copies the verified receipts that keep their values private into a directory for a pull request, byte for byte; refuses a receipt with plain arguments, results, or facts unless --allow-clear; never reads salts/, outbox/, or *.authorization.json; exits 1 when it refuses a receipt or copies none | verify |
reveal <bundle.json> --capture-key-env NAME --issuer-key <pub> [--out <file>] [--include-salts] | the values a receipt withheld under a capture rule, decrypted with the customer's key, as a disclosure file for verify --disclose | verify |
audit --older <bundle> --newer <bundle> (--log <log.jsonl> | --log-url <url>) [--issuer-key <pub>] [--log-key <pub>] [--log-id <id>] [--witness-key <pub> | --witness-url <url>] [--json] | proves the newer head extends the older | verify |
prune --log <log.jsonl> --before <ISO> [--receipts <dir>] | retention on a local log: older leaves become their hashes | log API |
log --file <log.jsonl> --key <log.key> [--port 8787] [--host] [--token-env NAME] [--log-id <id>] [--tenants <file>] | the log server over a file | log API |
log --db-env NAME (--key <log.key> [--retired-key <pub>]… | --signer-url <url> [--signer-token-env NAME]) [--checkpoint-dir <dir>] [--checkpoint-every 300] [--checkpoint-heartbeat 21600] [--admin-token-env NAME] [--public-url <url>] [--checkpoints-url <url>] [--trust-proxy] | the log server over Postgres, with tenants, checkpoints, and the admin page | log API |
signer --key <log.key> --port 8790 [--host] [--token-env NAME] [--retired-key <pub>]… | the process that holds the log's key | log API |
witness --key <witness.key> --log-url <url> --checkpoints-url <url> --out <dir> [--tenant <name>]… [--every 300] [--once] | a second signer on another operator's machine | log API |
anchor --log-url <url> --checkpoints-url <url> --out <dir> --rpc-url-env NAME --key-env NAME [--tenant <name>]… [--chain ethereum|base|arbitrum|optimism|polygon|<id>] [--max-fee-gwei <gwei>] [--every 21600] [--once] | commits the log's checkpoints to an EVM chain, Ethereum by default, one transaction per run that has something new | log API |
log-check --log-url <url> [--checkpoints-url <url>] [--witness-url <url>] [--tenant <name>]… [--max-lag 900] [--anchor-url <url> --anchor-address <0x…> --anchor-rpc-env NAME… --anchor-log-id <tenant>=<id>… [--anchor-chain ethereum] [--max-anchor-lag 46800]] [--json] | the outside monitor | log API |
log-export --log-url <url> [--tenant <name>] --token-env NAME --out <dir> [--month YYYY-MM]… [--json] | a tenant's own log, self-checked | verify |
portal --db-env NAME --secret-env NAME --public-url <url> [--checkpoints-url <url>] [--portal-url <url>] [--stripe-key-env NAME --stripe-webhook-env NAME --stripe-price-team <id>] [--mail-key-env NAME --mail-from <address> [--mail-notify <address>] [--mail-reply-to <address>]] [--trust-proxy] | the dashboard (app.agent-custody.dev); mail through Resend's API at sign-up | hosted |
portal-followup --db-env NAME --secret-env NAME --mail-key-env NAME --mail-from <address> [--mail-notify <address>] [--mail-reply-to <address>] [--signer <name>] [--signer-role <role>] [--portal-url <url>] [--dry-run] | the founder's note to registrations an hour to a week old that have not had it, once each, with a link to opt out; --secret-env names the portal's secret, which signs that link; --signer and --signer-role name who signs the note (default "The agent-custody team"); run hourly from cron | hosted |
log-admin --db-env NAME tenant add <id> [--log-id <id>] | tenant list | tenant disable <id> | tenant plan <id> <free|team|enterprise> | tenants | hosted |
log-admin --db-env NAME token add <tenant> --label <text> | token list <tenant> | token revoke <tenant> <hash-prefix> | tokens; a minted token is printed once | hosted |
log-admin --db-env NAME user mfa-reset <email> | turns MFA off for a portal account that lost its authenticator | hosted |
log-admin --db-env NAME sso set <tenant> (--oidc-issuer <url> --oidc-client-id <id> --oidc-secret-env NAME | --saml-entry-point <url> --saml-cert <pem file> [--saml-idp-issuer <id>]) --domains a.com,b.com [--default-role readonly] [--enforce] | sso show <tenant> | sso remove <tenant> | single sign-on for a tenant, through its own identity provider; the client secret is read from the environment | hosted |
log-admin --db-env NAME audit [--tenant <id>], log-admin --db-env NAME import --file <log.jsonl> [--tenant default] | the audit trail; a file log brought into the database | hosted |
portal --db-env NAME --secret-env NAME --public-url <log url> [--checkpoints-url <url>] [--portal-url <url>] [--port 8792] [--host] [--stripe-key-env NAME --stripe-webhook-env NAME --stripe-price-team <id>] [--trust-proxy] | the dashboard | hosted |
agent-custody-memory
| command | what it does | page |
|---|---|---|
serve --ledger <path> [--allow-direct] [--key <memory.key>] [--forget-key-env NAME] [--retention '<space>=<ISO duration>,…'] | the memory server over stdio | memory |
serve --ledger <path> --http [--port 8790] [--host] --token-env NAME [--allow-direct --direct-token-env NAME] | the same over HTTP, shared; the gateways' token and the direct writers' token are different | memory |
sweep --via <gateway.json> --reason <text> [--before <ISO>] [--space <space>] [--no-digest] | retention as a receipted call | state tools |
sweep --ledger <path> --before <ISO> --reason <text> [--space] [--actor] [--forget-key-env NAME] [--no-digest] | retention on the ledger alone | state tools |
repair --via <gateway.json> --reason <text> [--before <ISO instant>] | remove the store entries that the ledger has no fact for, as a receipted call | state tools |
eval [--scenarios <file>] [--baseline] [--json] [--sign <key> --out <report>], eval --verify <report> --key <pub> | the memory-mutation evals | state tools |
pack --ledger <path> --receipts <dir> --fact <factId> --out <pack.json> --sign <key>, pack --verify <pack.json> --key <pub> [--issuer-key] [--principal-key] | one fact's custody pack | state tools |
explain --receipts <dir> --receipt <id> [--ledger <path>] [--issuer-key] [--principal-key] [--log-key] [--json], explain … --out <file> --sign <key>, explain --verify <file> --key <pub> | one action explained | state tools |
review --receipts <dir> [--ledger <path>] [--issuer-key <pub>] [--principal-key <pub>] [--approval-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--log-id <id>] [--transaction <id>] [--customer <id>] [--agent <id>] [--from <ISO>] [--to <ISO>] [--port 8791] [--host] [--title <text>], review … --out <dir> | searchable review pages; exact public identifiers and inclusive time bounds; static search covers the exported set | state tools |
review --receipts <dir> --case <receiptId> --out <case.html|case.json> [--ledger <path>] [--issuer-key <pub>] [--principal-key <pub>] [--approval-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--log-id <id>] | one portable offline case, with receipts, authorizations, proofs, public keys and the ten answers | state tools |
review --verify-case <case.json|case.html> [--issuer-key <pub>] [--principal-key <pub>] [--approval-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--log-id <id>] [--json] | independently recomputes case verification from a case JSON or a .case.html, including the ten answers, which it prints; the file name sets the format (.json as JSON, every other name as a page; content that does not match fails); a page must be exactly what its data renders; supplied keys replace the bundled trust set; exit 1 on failure | state tools |
export --ledger <path> --out <ledger.jsonl> | any ledger as JSONL | state tools |
blast --ledger <path> --receipts <dir> --fact <factId> [--capture-key-env NAME] [--json] | what relied on a fact | state tools |