Version: v0.12.11

CLI Reference

The @peac/cli package provides command-line tools for issuing signed interaction records, capturing execution evidence, verifying receipts, creating evidence bundles, and generating signing keys.

Install

Terminal (global)
pnpm add -g @peac/cli

Or run directly without installing:

Terminal (npx)
npx peac <command>

Execution Records (v0.14.1+)

`peac observe command`

Capture an unsigned JSON observation of a CLI command. Does not require a signing key.

Terminal
# Observe a command -- returns unsigned JSON observation
peac observe command -- npm test

# Observe with output capture
peac observe command --capture-stdout -- node script.js

Flag	Description
`--capture-stdout`	Capture stdout (length + SHA-256 by default)
`--capture-stderr`	Capture stderr (length + SHA-256 by default)
`--json`	Output the observation as JSON

Security defaults: argv is hashed by default. stdin is none by default. Raw capture requires explicit double opt-in (--capture-mode raw --unsafe-allow-raw-capture). Shell binary detection without --shell-mode is a hard failure.

`peac record command`

Issue a signed interaction-record+jwt execution record for a CLI command. Requires a signing key and issuer URL.

Terminal
# Issue a signed execution record
peac record command \
  --signing-key $PEAC_SIGNING_KEY \
  --issuer https://api.example.com \
  -- npm test

# Issue with custom subject
peac record command \
  --signing-key $PEAC_SIGNING_KEY \
  --issuer https://api.example.com \
  --sub "ci:github-actions/build" \
  -- pnpm build

Flag	Description
`--signing-key`	Base64url-encoded Ed25519 private key
`--issuer`	Issuer URL (becomes `iss` in the signed record)
`--sub`	Subject identifier for this execution
`--capture-stdout`	Include stdout capture in the record
`--capture-stderr`	Include stderr capture in the record
`--capture-mode`	Capture mode: `hashed` (default) or `raw` (requires `--unsafe-allow-raw-capture`)
`--json`	Output the signed JWS as JSON

The signed record uses the org.peacprotocol/cli-execution extension namespace and org.peacprotocol/cli-command-execution type URI.

`peac emit lifecycle`

Emit a signed lifecycle observation record for an approval, evaluation, experiment, or workflow transition event.

Terminal
# Emit an approval-granted lifecycle record
peac emit lifecycle \
  --signing-key $PEAC_SIGNING_KEY \
  --issuer https://api.example.com \
  --event lifecycle-approval-granted \
  --approver-ref "ref:approver/ci-bot" \
  --request-ref "urn:request:pr-123"

# Emit a workflow transition record
peac emit lifecycle \
  --signing-key $PEAC_SIGNING_KEY \
  --issuer https://api.example.com \
  --event lifecycle-workflow-transition \
  --from-state pending \
  --to-state approved

Flag	Description
`--signing-key`	Base64url-encoded Ed25519 private key
`--issuer`	Issuer URL (becomes `iss` in the signed record)
`--event`	Event kind (see lifecycle event kinds below)
`--approver-ref`	Opaque reference to the approver (`ref:`, `urn:`, `did:`, `sha256:`, `https:` prefixes required)
`--request-ref`	Opaque reference to the approval request
`--from-state`	Source state for workflow transitions
`--to-state`	Target state for workflow transitions
`--json`	Output the signed JWS as JSON

Supported event kinds:

Event Kind	Description
`lifecycle-approval-requested`	Approval was requested for a change or action
`lifecycle-approval-granted`	Approval was granted by an authorized party
`lifecycle-approval-denied`	Approval was denied
`lifecycle-evaluation-started`	An evaluation (A/B test, policy check) was started
`lifecycle-evaluation-completed`	An evaluation completed with a result
`lifecycle-experiment-assigned`	A subject was assigned to an experiment group
`lifecycle-experiment-result`	An experiment result was recorded
`lifecycle-workflow-transition`	A workflow moved from one state to another
`lifecycle-mode-observed`	An operating mode was observed

The signed record uses the org.peacprotocol/lifecycle-observation extension namespace.

Opaque references required

All reference fields (approver_ref, request_ref, workflow_ref) must use opaque reference grammar: ref:, urn:, did:, sha256:, peac:, or https: prefixes. Raw email addresses, names, and free-form strings are rejected.

Verification

`peac verify`

Verify a receipt's signature and claims against an issuer's published keys.

Terminal
# Verify from a JWS string
peac verify <jws-string> --issuer https://api.example.com

# Verify from a file
peac verify --file receipt.jws --jwks keys.json

# Verify with policy binding
peac verify <jws-string> --issuer https://api.example.com --policy peac.txt

Flag	Description
`--issuer`	Issuer URL (fetches JWKS from `/.well-known/peac-issuer.json`)
`--jwks`	Path to a local JWKS file for offline verification
`--file`	Read the receipt from a file instead of a positional argument
`--policy`	Path to a `peac.txt` policy file for policy binding checks
`--json`	Output the verification result as JSON

`peac inspect`

Inspect a receipt's decoded contents without performing signature verification. Useful for debugging and examining claims.

Terminal
# Inspect from a JWS string
peac inspect <jws-string>

# Inspect from a file
peac inspect --file receipt.jws

Flag	Description
`--file`	Read the receipt from a file instead of a positional argument
`--json`	Output as JSON

`peac decode`

Decode a raw JWS into its three constituent parts: header, payload, and signature. No verification or claim interpretation is performed.

Terminal
peac decode <jws-string>

Output
Header:
  { "alg": "EdDSA", "typ": "interaction-record+jwt", "kid": "peac-2026-03" }

Payload:
  { "iss": "https://api.example.com", "sub": "agent:claude-123", ... }

Signature:
  <base64url-encoded-signature>

Flag	Description
`--json`	Output as JSON

Policy

`peac policy validate`

Validate a peac.txt or peac-policy.yaml policy document against the policy schema.

Terminal
# Validate a policy document
peac policy validate peac-policy.yaml

# Output detailed error report
peac policy validate peac.txt --json

Evidence Bundles

`peac bundle create`

Create an evidence bundle (peac-bundle/0.1) from one or more receipt files.

Terminal
peac bundle create \
  --receipts receipt1.jws receipt2.jws \
  --issuer https://api.example.com \
  --output evidence.zip

Flag	Description
`--receipts`	One or more receipt files to include in the bundle
`--issuer`	Issuer URL (fetches policy and keys for the manifest)
`--output`	Output file path for the evidence bundle
`--policy`	Include a specific policy file in the bundle

`peac reconcile`

Merge and compare two evidence bundles, detecting conflicts where the same receipt identity (iss, jti) maps to different content.

Terminal
# Merge two bundles and detect conflicts
peac reconcile bundle1.peac.tar.gz bundle2.peac.tar.gz

# Machine-readable JSON output
peac reconcile bundle1.peac.tar.gz bundle2.peac.tar.gz --format json

# Fail with exit code 1 if conflicts detected (CI-friendly)
peac reconcile bundle1.peac.tar.gz bundle2.peac.tar.gz --fail-on-conflict --format json

Flag	Description
`--format`	Output format: `text` (default) or `json` (deterministic, CI-friendly)
`--fail-on-conflict`	Exit code 1 when any conflict is detected (enables CI gate usage)

Key Management

`peac keygen`

Generate an Ed25519 keypair for receipt signing.

Terminal
npx @peac/cli keygen

Output
Private key (keep secret):
  <base64url-encoded-private-key>

Public key (publish at .well-known/peac-issuer.json):
  {
    "kty": "OKP",
    "crv": "Ed25519",
    "use": "sig",
    "kid": "peac-2026-03",
    "x": "<base64url-encoded-public-key>",
    "alg": "EdDSA"
  }

Keep your private key secret

The private key signs receipts on behalf of your service. Store it in an environment variable or secrets manager -- never commit it to version control.

Diagnostics

`peac doctor`

Run a diagnostics check to verify your PEAC setup: key validity, issuer configuration, policy document health, and connectivity.

Terminal
# Check local configuration
peac doctor

# Check with issuer URL
peac doctor --issuer https://api.example.com

# Output JSON report
peac doctor --json

`peac conformance run`

Run the PEAC conformance test suite against an issuer or verifier endpoint to check protocol compliance.

Terminal
# Run conformance suite against issuer
peac conformance run --issuer https://api.example.com

# Run specific conformance section
peac conformance run --issuer https://api.example.com --section RTGOV

# JSON output for CI
peac conformance run --issuer https://api.example.com --json

Exit codes

Code	Meaning
`0`	Success -- verification passed, record issued, or bundle created
`1`	Verification failed -- signature invalid or claims rejected
`2`	Invalid input -- malformed JWS, missing file, or bad arguments
`3`	Network error -- could not fetch JWKS or policy from issuer

Next steps

MCP Server

Expose the same verify, inspect, and decode tools to AI agents via MCP.

Verification

Understand the verification pipeline and trust model.

Install​

Execution Records (v0.14.1+)​

peac observe command​

peac record command​

peac emit lifecycle​

Verification​

peac verify​

peac inspect​

peac decode​

Policy​

peac policy validate​

Evidence Bundles​

peac bundle create​

peac reconcile​

Key Management​

peac keygen​

Diagnostics​

peac doctor​

peac conformance run​

Exit codes​

Next steps​

Install

Execution Records (v0.14.1+)

`peac observe command`

`peac record command`

`peac emit lifecycle`

Verification

`peac verify`

`peac inspect`

`peac decode`

Policy

`peac policy validate`

Evidence Bundles

`peac bundle create`

`peac reconcile`

Key Management

`peac keygen`

Diagnostics

`peac doctor`

`peac conformance run`

Exit codes

Next steps