CLI Reference

The @peac/cli package provides command-line tools for verifying receipts, inspecting claims, decoding tokens, 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>

---

Commands

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": "peac-receipt/0.1", "kid": "peac-2026-03" }

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

Signature:
  <base64url-encoded-signature>

Flag	Description
--json	Output as JSON

---

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, human-readable) or json (deterministic, CI-friendly)
--fail-on-conflict	Exit code 1 when any conflict is detected (enables CI gate usage)

The conflict key is a composite (iss, jti) with a 3-step fallback. JSON output is deterministic (sorted by (iss, jti)) for stable diffs across runs.

---

peac keygen

Generate an Ed25519 keypair for receipt signing. This is a standalone binary shipped alongside the CLI.

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.

---

Exit codes

Code	Meaning
0	Success -- verification passed 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.