CLI
Command-line tools for signed interaction record issuance, execution evidence capture, receipt verification, conformance testing, and policy authoring. Issue portable signed records, verify receipts, run conformance suites, and author peac.txt policies — all from the terminal.
Package: @peac/cli
Install
pnpm add @peac/cli # or with npm npm install @peac/cli
Commands
Execution Records New in v0.14.1
| Command | Description |
|---|---|
observe command | Capture CLI command execution as an unsigned JSON observation. Hash-by-default for argv and stdin; raw capture requires explicit opt-in. |
record command | Issue a signed Wire 0.2 execution record for a CLI command. Produces a portable interaction-record+jwt with execution metadata. |
emit lifecycle | Issue a signed lifecycle observation record — approval, evaluation, experiment assignment, workflow transition, or mode-observed events. |
Verification & Conformance
| Command | Description |
|---|---|
verify | Verify a receipt compact JWS: signature, claims, expiry, and kernel constraints |
conformance run | Run the conformance test suite against a receipt or issuer endpoint |
samples list | List built-in sample receipts for testing and demonstration |
Policy & Evidence Bundling
| Command | Description |
|---|---|
policy init | Create a new peac-policy.yaml template in the current directory |
policy validate | Validate a peac-policy.yaml file against the policy schema |
policy generate | Compile peac-policy.yaml into a peac.txt discovery file |
bundle create | Create an evidence bundle from one or more receipts |
keygen | Generate an Ed25519 key pair for receipt signing |
doctor | Run environment and configuration diagnostics for PEAC setup |
Execution Records New in v0.14.1
The observe command and record command verb-group surfaces capture CLI command execution as portable signed records. These records travel outside the system that produced them — allowing downstream verifiers to confirm bounded work happened without access to the originating environment.
# Unsigned observation (JSON, no key required)
$ peac observe command -- npm test
# Signed Wire 0.2 record (requires signing key)
$ peac record command \
--signing-key ./peac-signing-key.json \
--issuer https://ci.example.com \
-- npm test--capture-mode raw and --unsafe-allow-raw-capture. Environment variables are denied by default. Shell execution requires explicit --shell-mode.Lifecycle Records New in v0.14.1
The emit lifecycle command issues signed lifecycle observation records for orchestrator-sourced events: feature flag assignments, approval decisions, A/B experiment results, workflow transitions, and mode-observed signals.
# Emit a lifecycle approval-granted record
$ peac emit lifecycle \
--event-kind lifecycle-approval-granted \
--approver-ref did:key:z6Mk... \
--signing-key ./peac-signing-key.json \
--issuer https://ci.example.com
# Emit a workflow transition record
$ peac emit lifecycle \
--event-kind lifecycle-workflow-transition \
--from-state pending \
--to-state approved \
--signing-key ./peac-signing-key.jsonVerify
The verify command checks a receipt JWS against the issuer's public key. It validates the EdDSA signature, claim structure, expiry, and kernel constraints. The output is a structured JSON verification result.
$ peac verify eyJhbGciOiJFZERTQSIsInR5cCI6InBlYWMtcmVjZWlwdC8wLjEifQ...
{
"valid": true,
"issuer": "https://publisher.example.com",
"audience": "agent.consumer.com",
"issuedAt": "2026-02-25T12:00:00Z",
"expiresAt": "2026-02-25T13:00:00Z",
"wireFormat": "interaction-record+jwt",
"checks": {
"signature": "verified",
"claims": "verified",
"expiry": "verified",
"constraints": "verified"
}
}Conformance Levels
The conformance run command supports three levels of testing, each building on the previous:
| Level | Checks | Description |
|---|---|---|
basic | Structure + Signature | JWS format, required headers (alg, typ), EdDSA signature verification |
standard | + Claims + Expiry | Required claims (iss, iat), optional claims validation, expiry checks |
full | + Constraints + Policy binding | Kernel constraints, policy binding status, evidence carrier contract |
# Run standard conformance $ peac conformance run --level standard receipt.jws # Run full conformance against an issuer endpoint $ peac conformance run --level full --issuer https://publisher.example.com
Policy Authoring Workflow
The CLI provides a three-step workflow for authoring and publishing PEAC policies. The peac-policy.yaml file is the local source of truth; peac.txt is the hosted discovery artifact.
1. Initialize
Create a peac-policy.yaml template with default values:
$ peac policy init
2. Validate
Check the YAML against the policy schema before generating:
$ peac policy validate peac-policy.yaml
3. Generate
Compile the YAML into a peac.txt file for hosting at /.well-known/peac.txt:
$ peac policy generate peac-policy.yaml -o peac.txt
Evidence Bundling
The bundle create command combines multiple receipts into a single evidence bundle. Bundles are useful for compliance audits, dispute resolution, and archival.
$ peac bundle create \
--receipts receipt-1.jws receipt-2.jws receipt-3.jws \
--output evidence-bundle.jsonSample Receipts
The CLI ships with built-in sample receipts for testing and demonstration. Use samples list to see available samples, then pipe them to verify:
# List available samples $ peac samples list # Verify a built-in sample $ peac samples get payment-x402 | peac verify
Links
Verify and Author from the Terminal
The CLI covers the full receipt lifecycle: verify incoming receipts, run conformance tests against your implementation, author policies for your domain, and bundle evidence for audits. All operations run locally; no network calls are made unless you explicitly target a remote issuer endpoint.