agentpki CLI

Terminal interface for AgentPKI. Mint, verify, decode, tamper, and inspect agent passports from anywhere.

Install

npm i -g agentpki

Usage

# Mint a demo passport
agentpki mint
agentpki mint --scope=read:articles --sub=agent:mybot/v1

# Verify a token (pipe-friendly: `-` reads from stdin)
agentpki verify v4.public.eyJpc3M...
echo $TOKEN | agentpki verify -

# Decode any PASETO token to JSON (no signature check)
agentpki decode v4.public.eyJpc3M...

# Diff two tokens — claims, footer, sig + live verdicts side by side
agentpki diff v4.public.AAA v4.public.BBB
agentpki diff --json $TOK_OLD $TOK_NEW       # JSON output for scripting
agentpki diff --skip-verify $A $B            # no verifier round-trip
# Diff two tokens piped from another tool:
printf '%s\n%s\n' "$A" "$B" | agentpki diff - -

# Batch-verify many tokens (one per line)
agentpki batch tokens.txt                    # streaming verdicts + summary
agentpki batch tokens.txt --concurrency=16   # bump parallelism (default 8, max 32)
agentpki batch - < tokens.txt                # read from stdin
agentpki batch tokens.txt --ndjson > out.jsonl  # streaming JSON per line
agentpki batch tokens.txt --json | jq '.summary'

# Tamper a token (default: signature byte-flip)
agentpki tamper v4.public.eyJpc3M...
agentpki tamper $TOKEN --mode=payload | agentpki verify -

# Check whether a URL participates in AgentPKI (looks for AgentPKI-Token header)
agentpki check https://example.com/api/articles/123

# Inspect an issuer's CRL
agentpki crl https://demo.agentpki.dev

# Scaffold a new project
agentpki init --dir=./my-agent

Pipe-friendly

Every command writes the canonical result (a token, a verdict) to stdout, so you can chain:

agentpki mint | agentpki verify -
# verdict: allow (verifier 240 ms)

agentpki mint | agentpki tamper --mode=sig - | agentpki verify -
# verdict: deny
# reason:  bad_signature
# elapsed: 3 ms

Exit codes

| Code | Meaning | |---|---| | 0 | Verdict was allow (or command succeeded) | | 1 | Verdict was deny (or fetch failure) | | 2 | Usage error (missing arg, unknown command) |

This makes the CLI usable in CI:

# CI guard: fail the build if the trust contract regresses
agentpki mint | agentpki verify - || exit 1
agentpki mint | agentpki tamper - | agentpki verify - && echo "REGRESSION: tampered token allowed" && exit 1

Environment variables

| Var | Default | |---|---| | AGENTPKI_VERIFIER | https://verify.agentpki.dev | | AGENTPKI_DEMO_ISSUER | https://demo.agentpki.dev |

Build from source

git clone https://github.com/agentpki/cli
cd cli
npm install
npm run build
npm link              # makes `agentpki` available globally

License

MIT.