CLI Usage

The idprova CLI is the fastest way to work with the IDProva protocol. Generate keys, create agent identities, issue delegation tokens, inspect and verify tokens, and check audit receipt integrity — all from your terminal.

Installation

Cargo

cargo install idprova-cli

From Source

git clone https://github.com/techblaze-au/idprova.git
cd idprova
cargo install --path crates/idprova-cli

Docker

docker pull techblaze/idprova:latest
docker run --rm techblaze/idprova idprova --help

Common Workflows

Create an Agent Identity (End-to-End)

1. Generate a keypair

   idprova keygen --output ~/.idprova/keys/alice.key

   Outputs the hex-encoded secret key and multibase public key.

2. Create an AID

   idprova aid create \
     --id "did:idprova:example.com:my-agent" \
     --name "My Agent" \
     --controller "did:idprova:example.com:alice" \
     --model "anthropic/claude-opus-4" \
     --runtime "custom/v1.0" \
     --key ~/.idprova/keys/alice.key

   Outputs the signed AID (W3C DID Document) as JSON.

3. Verify the AID

   idprova aid verify my-agent-aid.json

   Validates the document structure, key formats, and metadata fields.

Issue and Verify Delegation Tokens

# Issue a scoped delegation token (24 hour expiry)
idprova dat issue \
  --issuer "did:idprova:example.com:alice" \
  --subject "did:idprova:example.com:my-agent" \
  --scope "mcp:tool:*:read,mcp:resource:docs:write" \
  --expires-in "24h" \
  --key ~/.idprova/keys/alice.key

# Verify a DAT (checks timing and claims)
idprova dat verify "eyJhbGciOiJFZERTQSIs..."

# Inspect a DAT without verifying (decode and pretty-print)
idprova dat inspect "eyJhbGciOiJFZERTQSIs..."

Verify Audit Receipts

# Verify the hash chain integrity of a receipt log
idprova receipt verify receipts.jsonl

# Show receipt statistics (action types, entry counts)
idprova receipt stats receipts.jsonl

Command Reference

Command	Description
idprova keygen	Generate an Ed25519 keypair
idprova aid create	Build and sign an AID document
idprova aid verify	Validate an AID from a JSON file
idprova aid resolve	Resolve an AID from a registry
idprova dat issue	Issue a signed delegation token
idprova dat verify	Verify DAT timing and claims
idprova dat inspect	Decode and pretty-print a DAT
idprova receipt verify	Verify receipt hash chain integrity
idprova receipt stats	Show receipt log statistics

See CLI Commands Reference for full option documentation.

Environment Variables

Variable	Default	Description
IDPROVA_REGISTRY	registry.idprova.dev	Registry server URL
IDPROVA_KEY_DIR	~/.idprova/keys/	Default key storage directory

CI/CD Integration

The CLI works well in CI pipelines for automated identity and token management:

# GitHub Actions example
- name: Verify agent identity
  run: idprova aid verify agent-identity.json

- name: Verify delegation chain
  run: idprova dat verify "$DAT_TOKEN"

- name: Check receipt integrity
  run: idprova receipt verify receipts.jsonl

Next Steps

• CLI Commands Reference — Full command and flag documentation
• Running a Registry — Set up your own IDProva registry
• Quick Start — Guided walkthrough with the CLI