CLI Reference

vouch init

# Via flag
vouch sign --json --payload '{"msg":"hello"}'

# Via stdin with scope
echo '{"msg":"hello"}' | vouch sign --json --scope messaging

{
  "envelope": {
    "v": 1,
    "agent_id": "0x...",
    "signer": "0x...",
    "ts": 1760000000,
    "exp": 1760003600,
    "nonce": "0x...",
    "scope": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "payload_hash": "0x...",
    "sig": "0x..."
  },
  "payload": { "msg": "hello" }
}

# Pipe from sign
vouch sign --json --payload '{"x":1}' | vouch verify --json

# From a file
cat signed.json | vouch verify --json

{
  "valid": true,
  "signer": "0x...",
  "identities": [
    { "provider": "x", "label": "alice" },
    { "provider": "github", "label": "alice-dev" }
  ],
  "scope": "0x0000...0000",
  "scope_matched": true,
  "failure_reason": "",
  "checked_at": "2026-02-19T20:00:00Z"
}

# Send by handle
echo '{"action":"hello"}' | vouch send @stripe

# Send with inline payload
vouch send @stripe --payload '{"action":"refund","amount":"50.00"}'

# Send to explicit URL
echo '{"msg":"hi"}' | vouch send --url https://agent.stripe.com/vouch

# Send with scope
echo '{"action":"pay"}' | vouch send @stripe --scope payments

{
  "accepted": true,
  "message": "refund initiated"
}

# Start a receiver with handler script
vouch receive --port 8080 --handler ./process.sh

# Start with allowlist filtering
vouch receive --port 8080 --handler ./process.sh --allowlist

{
  "sender": {
    "agent_id": "0x...",
    "identities": [
      { "provider": "x", "label": "stripe" }
    ]
  },
  "payload": {
    "action": "request_refund",
    "amount": "50.00"
  },
  "verified_at": "2026-02-28T10:30:00Z"
}

vouch agent create

api/
  vouch.js (or vouch.py)  # Vercel serverless function
handler.mjs (or .py)      # Local handler for testing
.env                      # OPENAI_API_KEY (0600 perms)
package.json              # (Node.js only)
requirements.txt          # (Python only)
vercel.json               # Vercel routing config
vouch-agent.toml          # Agent metadata

vouch agent start my-agent

# Then send it a test message from another terminal:
echo '{"action":"hello"}' | vouch send --url http://localhost:8080/vouch

# Preview deployment
vouch agent deploy my-agent

# Production deployment
vouch agent deploy my-agent --prod

vouch delegate --json --wallet-key 0x... --expiry 24h --scope messaging

vouch lookup --json @alice
vouch lookup --json --wallet 0x...
vouch lookup --json --github alice-dev
vouch lookup --json --domain stripe.com
vouch lookup --json --capability chat

vouch whoami --json

vouch status --json

vouch publish --json --wallet-key 0x... \
  --endpoint https://agent.example.com/vouch \
  --capabilities "messaging,payments"

vouch revoke-key --json --wallet-key 0x... --key 0xRUNTIME_KEY

# Revoke GitHub identity
vouch revoke-link --json --wallet-key 0x... --provider github

# Revoke X identity
vouch revoke-link --json --wallet-key 0x... --provider x

vouch link-x --json \
  --wallet-key 0x... \
  --attestation '{"x_user_id":"123","x_handle":"alice",...}'

vouch link-github --json --wallet-key 0x...

vouch link-dns --json --wallet-key 0x... --domain mycompany.com

# The command will output a TXT record to add:
# _vouch.mycompany.com TXT "vouch-verify=abc123..."
# After adding the record, run link-dns again to complete verification.

vouch allowlist add @alice
vouch allowlist remove @alice
vouch allowlist list

vouch sign --json --payload '{"action":"deploy","id":"cr-42"}' \
  | vouch verify --json \
  | jq '{valid, signer, identities, scope_matched}'

echo '{"action":"refund","amount":"50.00"}' \
  | vouch send @stripe --scope payments

while IFS= read -r line; do
  echo "$line" | vouch verify --json | jq -c '{valid, signer}'
done < envelopes.jsonl

vouch lookup --json --key 0xRUNTIME_KEY | jq '.found'

# X or GitHub is linked during vouch init (creates your API account)
# Add additional providers after init:

# Add GitHub (if you linked X during init)
vouch link-github --json --wallet-key $WALLET_KEY

# Add domain (requires existing API account)
vouch link-dns --json --wallet-key $WALLET_KEY --domain mycompany.com

# Check all linked identities
vouch whoami --json | jq '.identities'

# Create an agent (interactive wizard)
vouch agent create

# Test locally
vouch agent start my-agent

# Deploy to Vercel
vouch agent deploy my-agent --prod

# Register in directory so others can find you
vouch publish --endpoint https://my-agent-abc123.vercel.app/api/vouch \
  --capabilities "support,chat"

# 1. Delegate a scoped runtime key
DELEGATE=$(vouch delegate --json --wallet-key $WALLET_KEY \
  --expiry 24h --scope messaging)
RUNTIME_KEY=$(echo "$DELEGATE" | jq -r '.runtime_key')

# 2. Publish your endpoint
vouch publish --json --wallet-key $WALLET_KEY \
  --endpoint https://myagent.com/vouch \
  --capabilities "messaging,support"

# 3. Start receiving
vouch receive --port 8080 --handler ./handle_message.sh

# 4. When done, revoke
vouch revoke-key --json --wallet-key $WALLET_KEY --key $RUNTIME_KEY