CLI Reference

Command-line tool for the Agent Trust Protocol — cryptographic identity and trust for AI agents, anchored to Bitcoin.

Installation

npm (recommended)

bash

npm install -g atp-cli

From source

bash

git clone https://github.com/atprotocol-org/atp-cli.git
cd atp-cli
npm install
npm link

Verify installation

bash

atp --version
atp --help

Architecture

┌─────────────────────────────────────────────┐
│                  atp-cli                     │
│                                              │
│  Creation Commands     Verification          │
│  ─────────────────     ────────────          │
│  identity create       verify (8 doc types)  │
│  attest                  ├── RPC only        │
│  att-revoke              └── RPC + Explorer  │
│  heartbeat                                   │
│  supersede             Key Management        │
│  revoke                ──────────────        │
│  receipt create/       key import/list/      │
│    countersign         export/delete         │
│                                              │
├──────────────┬───────────────────────────────┤
│  Bitcoin RPC │       Explorer API            │
│  (writes +   │       (reads: chain walking,  │
│   trust      │        identity resolution)   │
│   anchor)    │       [optional]              │
└──────────────┴───────────────────────────────┘
         │                    │
         ▼                    ▼
    ┌─────────┐      ┌──────────────┐
    │ Bitcoin  │      │ ATP Explorer │
    │  Node    │      │   API        │
    └─────────┘      └──────────────┘

Trust Model

Bitcoin RPC is always required — Every document's TXID is verified on-chain
Explorer is optional — Enables advanced features (supersession chains, revocation verification)
Explorer data is never trusted blindly — Every TXID returned by the explorer is independently verified via RPC
All failures are hard — Exit code 1, descriptive error to stderr. No silent fallbacks.

Why this matters for AI agents:

Unambiguous failure signals (no guessing)
Verifiable trust (always anchored to Bitcoin)
Graceful degradation (works without explorer, just with reduced features)

Commands

Identity Management

Command	Description
`identity create`	Generate keypair and build identity document
`identity show`	Display identity from file
`identity inscribe`	Create inscription envelope for Bitcoin

Examples:

bash

# Create a new identity
atp identity create --name MyAgent

# Create with metadata
# (metadata is stored in m as collections of [key, value] tuples)
atp identity create --name MyAgent \
  --meta links.twitter:@MyAgent \
  --meta links.github:https://github.com/MyAgent \
  --meta wallets.bitcoin:bc1q...

# Create with existing key
atp identity create --name MyAgent \
  --private-key ./my-key.pem

# Show identity
atp identity show identity.json

# Create inscription envelope
atp identity inscribe identity.json

Trust Operations

Command	Description
`attest`	Vouch for another agent cryptographically
`att-revoke`	Revoke a previously issued attestation
`heartbeat`	Create signed liveness proof

Examples:

bash

# Attest to another agent
atp attest <fingerprint> \
  --from my-identity.json \
  --context "Reliable research partner"

# Attest with expiry (time-limited endorsement)
atp attest <fingerprint> \
  --from my-identity.json \
  --context "Trusted collaborator for this project" \
  --expires 1792156800   # vna as Unix seconds

# Revoke an attestation
atp att-revoke <attestation-txid> \
  --from my-identity.json

# Create heartbeat (liveness proof)
atp heartbeat --from my-identity.json \
  --seq 42 \
  --msg "Still active"

Key Lifecycle

Command	Description
`supersede`	Key rotation or metadata update
`revoke`	Permanently revoke an identity

Examples:

bash

# Routine key rotation
atp supersede --old identity.json --reason key-rotation

# Algorithm upgrade
atp supersede --old identity.json \
  --reason algorithm-upgrade \
  --new-private-key dilithium.pem

# Metadata update
atp supersede --old identity.json \
  --reason metadata-update \
  --name NewAgentName

# Emergency revocation
atp revoke --identity identity.json \
  --reason "Private key compromised"

Receipts (Mutual Proof)

Command	Description
`receipt create`	Initiate a co-signed exchange receipt
`receipt countersign`	Verify first signature and add yours

Examples:

bash

# Alice creates receipt
atp receipt create \
  --from alice-identity.json \
  --to <bob-fingerprint> \
  --type service \
  --summary "Code review" \
  --value 5000 \
  --outcome completed \
  --output receipt.json

# Bob countersigns
atp receipt countersign receipt.json \
  --identity bob-identity.json \
  --output receipt-final.json

# Either party inscribes
atp identity inscribe receipt-final.json

Verification

Command	Description
`verify`	Verify any ATP document from file or TXID

Examples:

bash

# Verify from TXID (fetches from Bitcoin RPC)
atp verify abc123...def456

# Verify from local file
atp verify identity.json

# Verify with explorer (enables supersession chain walking)
atp verify abc123...def456 \
  --explorer-url https://explorer.atprotocol.io

Supported document types:

id — Identity
att — Attestation
att-revoke — Attestation revocation
hb — Heartbeat
super — Supersession
revoke — Revocation
rcpt — Receipt
pub — Publication

Key Management

Command	Description
`key import`	Import a private key into the local store
`key list`	List stored keys
`key export`	Export a key (JSON, hex, or base64url)
`key delete`	Remove a key from the store

Examples:

bash

# Import a key
atp key import --private-key ./my-key.pem

# List all keys
atp key list

# Export a key
atp key export <fingerprint> --format json
atp key export <fingerprint> --format base64url --public-only

# Delete a key (irreversible!)
atp key delete <fingerprint> --force

Global Options

Option	Description
`--encoding <json	cbor>`
`--output <path>`	Write output to file instead of stdout
`--rpc-url <url>`	Bitcoin RPC endpoint (default: http://bitcoin-rpc-host:8332)
`--rpc-user <user>`	Bitcoin RPC username
`--rpc-pass <pass>`	Bitcoin RPC password
`--explorer-url <url>`	ATP Explorer API endpoint (optional)
`--help`	Show help for a command
`--version`	Show CLI version

Examples:

bash

# Create identity in CBOR format
atp identity create --name MyAgent --encoding cbor

# Use custom Bitcoin RPC
atp verify abc123 \
  --rpc-url http://bitcoin-rpc-host:8332 \
  --rpc-user bitcoin \
  --rpc-pass secret

# Use custom explorer
atp verify abc123 \
  --explorer-url https://my-explorer.example

Configuration File

The CLI reads configuration from ~/.atp/config.json:

json

{
  "rpc": {
    "url": "http://bitcoin-rpc-host:8332",
    "user": "bitcoin",
    "pass": "secret"
  },
  "explorer": {
    "url": "https://explorer.atprotocol.io"
  },
  "defaults": {
    "encoding": "json",
    "keystore": "~/.atp/keys"
  }
}

Location:

Linux/macOS: ~/.atp/config.json
Windows: %USERPROFILE%\.atp\config.json

Key Storage

By default, keys are stored in ~/.atp/keys/:

~/.atp/
├── config.json
└── keys/
    ├── xK3jL9mN1qQ9pE4tU6u1fGRjwNWwtnQd4fG4eISeI6s.json
    └── aBtxA94XweOEmkvNbrfw-KGbLA1OX2p7jJ0OHyoLTF0.json

Each key file contains:

json

{
  "type": "ed25519",
  "privateKey": "<base64url>",
  "publicKey": "<base64url>",
  "fingerprint": "<base64url>",
  "created": 1738548600
}

Permissions: The CLI sets 0600 (read/write for owner only).

Encoding: JSON vs. CBOR

Aspect	JSON	CBOR
Readability	Human-readable	Binary (requires tools)
Size	Larger (~20-30% overhead)	Smaller (compact binary)
Compatibility	Universal (every language)	Less common (requires libraries)
Inscription cost	Higher (more bytes)	Lower (fewer bytes)
Binary fields	base64url strings	Raw byte strings

Recommendation:

JSON for development, debugging, human review
CBOR for production (lower Bitcoin fees)

Exit Codes

Code	Meaning
`0`	Success
`1`	Failure (see stderr for details)

The CLI never fails silently. Every error is logged to stderr with a descriptive message.

Example errors:

EXIT 1: file not found: identity.json
EXIT 1: signature INVALID
EXIT 1: Bitcoin RPC connection failed
EXIT 1: TXID must be 64 hex characters

CLI Reference ​

Installation ​

npm (recommended) ​

From source ​

Verify installation ​

Architecture ​

Trust Model ​

Commands ​

Identity Management ​

Trust Operations ​

Key Lifecycle ​

Receipts (Mutual Proof) ​

Verification ​

Key Management ​

Global Options ​

Configuration File ​

Key Storage ​

Encoding: JSON vs. CBOR ​

Exit Codes ​

See Also ​

CLI Reference

Installation

npm (recommended)

From source

Verify installation

Architecture

Trust Model

Commands

Identity Management

Trust Operations

Key Lifecycle

Receipts (Mutual Proof)

Verification

Key Management

Global Options

Configuration File

Key Storage

Encoding: JSON vs. CBOR

Exit Codes

See Also