CLI

Installed binary name: aegis. This page documents main.

aegis <version> — research runtime for secure agent tool execution

Usage:
  aegis [--policy <PATH>] [--audit <PATH> --signing-key <PATH>]
  aegis run --component <WASM> --id <TOOL_ID> [OPTIONS]
  aegis wrap --audit <PATH> --signing-key <PATH> [--policy <YAML>] [--confine] -- <CMD> [ARGS…]
  aegis verify [--key <HEX>]... [--trust-store <PATH>] <PATH>
  aegis recheck --policy <YAML> <PATH>
  aegis keygen --out <PATH> [--force]

Only run is in the published 0.3.0 binary. keygen, verify, recheck, and wrap landed after that tag and reach the registry with the next cut — until then, build from source.

Full flag tables: crates/botzr-aegis-cli/README.md.

aegis keygen

Writes a fresh ed25519 seed to --out as 64 lowercase hex characters. Prints public_key and key_id. Generation is never implicit — a key minted on the emit path would silently invalidate every pin held against the old one.

On Unix the file is created 0600, and aegis refuses to load a key readable by group or others. Elsewhere the mode is neither set nor checked: there is no portable equivalent, and claiming one would be a guarantee the code cannot keep.

aegis run

Registers a wasm32-wasip2 component and executes one call through the pipeline. --audit and --signing-key travel together, or neither is given.

Without --audit, nothing is kept. Bare aegis and aegis run with no --audit write to a Volatile, in-memory sink and print

Audit: (volatile sink — records are not retained)

instead of a path. The bytes die with the process: there is no file to open afterwards, nothing for aegis verify or aegis recheck to read, and the Session is signed by the dev key compiled into botzr-aegis-audit — so it is not evidence, and never was. Naming a path there would be the overclaim (ADR-0012).

To get a retained record, pass --audit <PATH> and --signing-key <PATH>. That is a Durable sink, and a Durable sink refuses the dev key — which is why the two flags travel together rather than one of them defaulting.

The published 0.3.0 binary differs here. At tag v0.3.0 there is no --signing-key at all: --audit <PATH> is accepted alone, and the records it writes are unsigned — no signing code shipped at that tag, so a 0.3.0 audit file carries no signature to attribute and aegis verify has nothing to check. It also defaults to a temp file sink and prints that /tmp/…/audit.jsonl path for a directory it deletes at exit (verified 2026-08-14 against the shipped binary). Signing, the in-memory default, and therefore the requirement that the two flags travel together, are main changes that reach the registry with the next cut. Flags on this page are main’s; do not read them against an installed 0.3.0.

aegis wrap

Interpose on a child stdio MCP server and record every tools/call.

Two independent opt-ins, neither on by default:

• --policy <YAML> evaluates every well-formed tools/call before the frame may reach the child. A denied one never reaches it and the client is answered with JSON-RPC -32042 rather than left blocked on an id (ADR-0015). Without --policy wrap evaluates no rules and blocks nothing — every tools/call is relayed, and the client stream is byte-for-byte the child’s. A rule here matches tool identity; wrap never inspects params.arguments, and mints no capability under either mode, so even an allowed call records the deny_all pass-through grant.
• --confine applies Landlock and seccomp to the child process, on Linux, and records what the kernel actually enforced. It is not a per-call decision and answers a different question from --policy.

See Wrapping an MCP server for the full non-guarantee list.

aegis verify

Reads one Chain file and reports a verdict. Exit codes are API (ADR-0002):

Two trust states (ADR-0004):

• Verified (unpinned) — every signature checks out against the key the file itself published. Internal consistency only. An attacker who rewrites a whole Session signs it with their own key and the walk comes out clean.
• Verified (pinned to <fp>) — same walk, plus every open key was one you supplied out of band. That is the provenance claim.

A pinned file that legally rotates across several anchored keys has no single fingerprint to name, so it prints bare Verified (pinned) — still the provenance claim, just over more than one key (SPEC.md §8.4).

A quickstart that prints bare Verified without saying which is an overclaim.

aegis recheck

Re-evaluates every recorded outcome against a new Policy Set and prints a would-block diff. Nothing is executed. The command is recheck, never replay (ADR-0008).

--policy is required. An implicit allow-all set would answer a question nobody asked.

3 outranks 1. Recheck does not verify signatures; asking what today’s rules would have done to a file verify would call Tampered is a legitimate forensic question.