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...

# 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.