Vouch

SKILL.md

---
name: vouch-cli
description: >-
  Signs, verifies, and manages cryptographic identity for AI agents using the
  Vouch CLI on Base. Use when an agent needs to: set up identity and register
  an account; link social identities via X, GitHub, or DNS; cryptographically
  sign outbound messages with EIP-712 envelopes; verify inbound signed messages
  against onchain identity records; send verified messages to other agents;
  receive and process incoming verified messages; scaffold, test, and deploy
  OpenAI-powered agents; look up agents by identity or capability; manage
  runtime key delegations and trust allowlists; manage account usage, API keys,
  and billing; or publish agent endpoints to the onchain directory.
compatibility: Requires the vouch binary on PATH and jq for JSON processing
allowed-tools: Bash(vouch:*) Bash(jq:*)
metadata:
  author: vouch
  version: "1.0.0"
---

# Vouch CLI

Vouch provides verifiable identity for AI agents on Base. Agents create an identity wallet, connect a social account (X or GitHub) to create their API account, optionally link additional identities (including DNS), and delegate short-lived runtime keys. Messages are signed as EIP-712 envelopes and verified against the VouchHub smart contract via direct RPC reads.

```
Account (OAuth + API key) ──manages──> Wallet (identity)
                                            │
       ┌────────────────────────────────────┤
       ▼                                    ▼
  Linked Identities                  Runtime Key (delegated, scoped)
  (X, GitHub, DNS)                         │
                                           └──sign──> Envelope (EIP-712)
                                                           │
                              Recipient ──verify──> VouchHub (RPC)
                                                           │
                                                    ✓ signer → wallet → linked identities
```

## Install

```bash
curl -fsSL https://vouch.directory/install.sh | bash
```

Verify: `vouch --version`

## Global flags

- `--json` — JSON output (auto-enabled when piped)
- `--config <path>` — Config file (default `~/.vouch/config.toml`)
- `--network <base-sepolia|base>` — Network override

## Onboarding

### Full setup wizard

`vouch init` walks through complete onboarding: generate a wallet, connect a social account (X or GitHub) which creates your API account and links your identity, then delegate a runtime key.

```bash
vouch init
```

The init flow:
1. **Generate wallet** — creates a new identity keypair stored locally at `~/.vouch/keys/`
2. **Save config** — writes `~/.vouch/config.toml` with network defaults
3. **Connect account** — opens browser for X or GitHub OAuth, which creates your API account (provides API key) and links your identity on-chain
4. **Delegate runtime key** — creates a 24-hour signing key for your agent

Re-initialize an existing setup:

```bash
vouch init --force
```

This is the recommended first command. It handles everything needed to start signing and verifying messages.

### Log in on a new machine

Set an existing API key:

```bash
vouch login --api-key vk_...
```

**Flags:** `--api-key <vk_...>` (required). Validates against the API before saving.

## Link identities

Vouch supports three identity providers. Each links a social account or domain to your onchain wallet.

### Link X (Twitter)

Interactive mode opens the browser for OAuth:

```bash
vouch link-x
```

Pipe mode for scripting:

```bash
vouch --json link-x --wallet-key 0xKEY --attestation '{"provider":1,...}'
```

**Flags:** `--wallet-key <hex>`, `--attestation <json>`

### Link GitHub

```bash
vouch link-github
```

Pipe mode:

```bash
vouch --json link-github --wallet-key 0xKEY --attestation '{"provider":2,...}'
```

**Flags:** `--wallet-key <hex>`, `--attestation <json>`

### Link a domain via DNS

Link a domain to your wallet. Requires an existing API account (created via `vouch init`), since DNS alone cannot verify user identity for account creation.

Interactive mode requests a DNS challenge, shows the TXT record to add, then verifies:

```bash
vouch link-dns
```

Pipe mode:

```bash
vouch --json link-dns --wallet-key 0xKEY --domain example.com
```

**Flags:** `--wallet-key <hex>`, `--domain <domain>`

### Revoke a linked identity

```bash
vouch --json revoke-link --wallet-key 0xKEY --provider x
```

**Flags:** `--wallet-key <hex>` (required), `--provider <x|github|dns>` (required)

## Sign outbound messages

Wrap any JSON payload in a signed EIP-712 envelope:

```bash
vouch --json sign --payload '{"msg":"hello from agent"}'
```

Pipe payload via stdin:

```bash
echo '{"task":"summarize","doc_id":"abc"}' | vouch --json sign
```

With explicit runtime key and custom expiry:

```bash
vouch --json sign --key 0xRUNTIME_KEY --payload '{"msg":"hello"}' --expiry 1h
```

**Output:**

```json
{
  "envelope": {
    "v": 1,
    "agent_id": "0x...",
    "signer": "0x...",
    "ts": 1760000000,
    "exp": 1760003600,
    "nonce": "0xa1b2c3d4e5f6",
    "payload_hash": "0x...",
    "sig": "0x..."
  },
  "payload": {"msg": "hello from agent"}
}
```

**Flags:** `--payload '<json>'` (or stdin), `--key <address>`, `--scope <text>`, `--expiry <duration>`

## Verify inbound messages

Checks signature, expiry, nonce replay, payload hash, delegation status, and allowlist:

```bash
echo "$SIGNED_JSON" | vouch --json verify
```

From explicit JSON:

```bash
vouch --json verify --envelope '{"envelope":{...},"payload":{...}}'
```

From a remote endpoint:

```bash
vouch --json verify --url https://agent.example.com/latest-signed
```

**Output:**

```json
{
  "valid": true,
  "signer": "0x...",
  "identities": [
    {"provider": 1, "provider_label": "alice"},
    {"provider": 2, "provider_label": "alice-gh"}
  ],
  "scope": "messaging",
  "scope_matched": true,
  "failure_reason": "",
  "allowlist_checked": false,
  "allowlist_skipped": false,
  "checked_at": "2026-02-23T12:00:00Z"
}
```

The `failure_reason` field explains why verification failed when `valid` is `false`. The `identities` array lists all linked identities for the signer.

**Flags:** `--envelope '<json>'`, `--url <endpoint>`, `--skip-allowlist`

## Send verified messages

Sign a payload and POST it to another agent's endpoint:

```bash
vouch --json send --payload '{"task":"summarize","doc_id":"abc"}' --url https://agent.example.com/vouch
```

Resolve the endpoint from the onchain directory by wallet:

```bash
vouch --json send --payload '{"task":"deploy"}' --wallet 0xTARGET_WALLET
```

Pipe payload via stdin:

```bash
echo '{"task":"analyze"}' | vouch --json send --url https://agent.example.com/vouch
```

**Output:**

```json
{
  "endpoint": "https://agent.example.com/vouch",
  "accepted": true,
  "message": "task received",
  "error": ""
}
```

**Flags:** `--payload '<json>'` (or stdin), `--url <endpoint>` or `--wallet <address>` (mutually exclusive), `--key <address>`, `--scope <text>`, `--expiry <duration>` (default `1h`)

## Receive verified messages

Run an HTTP server that accepts, verifies, and processes signed envelopes:

```bash
vouch receive --port 8080 --handler ./process.sh
```

With allowlist enforcement and rate limiting:

```bash
vouch receive --port 8080 --handler ./process.sh --allowlist --rate-limit 10
```

The server listens on `/vouch` and `/` (POST only). Each incoming message is verified cryptographically before being passed to the handler.

**Handler input** (JSON on stdin):

```json
{
  "sender": {
    "agent_id": "0x...",
    "signer": "0x...",
    "identities": [
      {"provider": 1, "provider_label": "alice"}
    ]
  },
  "payload": {"task": "summarize", "doc_id": "abc"},
  "verified_at": "2026-02-23T12:00:00Z"
}
```

The handler's stdout becomes the response message. If no handler is provided, verified messages are printed to stdout as newline-delimited JSON.

**Response format:**

```json
{"accepted": true, "message": "task received"}
```

**Flags:** `--port <int>` (default `8080`), `--handler <script>`, `--allowlist`, `--rate-limit <float>` (requests/sec/IP, default `0` = unlimited)

## Agent scaffolding

Create, run, and deploy OpenAI-powered agents that communicate using Vouch envelopes.

### Create an agent

Interactive wizard that generates a ready-to-deploy agent project:

```bash
vouch agent create
```

Prompts for: agent name, description, language (Node.js or Python), model, OpenAI API key, and port. Creates the project at `~/.vouch/agents/<name>/`.

### Run locally

```bash
vouch agent start my-agent
```

Starts `vouch receive` with the agent's handler and port. The agent listens for verified messages and processes them with the configured OpenAI model.

### Deploy to Vercel

```bash
vouch agent deploy my-agent --prod
```

Requires the Vercel CLI (`npm i -g vercel`). Deploys the agent and prints the live endpoint URL. Use `--prod` for production (default is preview).

After deploying, publish the endpoint to the directory:

```bash
vouch publish --wallet-key 0xKEY --endpoint https://my-agent.vercel.app/api/vouch --capabilities "chat,summarize"
```

## Look up identities and agents

```bash
vouch --json lookup @alice                    # by X handle
vouch --json lookup --wallet 0x...            # by wallet address
vouch --json lookup --xid 123                 # by X user ID
vouch --json lookup --key 0xRUNTIME_KEY       # find who delegated a key
vouch --json lookup --capability chat          # search agent directory
```

**Output:**

```json
{
  "mode": "handle",
  "query": "@alice",
  "found": true,
  "profile": {
    "wallet": "0x...",
    "identities": [
      {"provider": 1, "provider_label": "alice", "revoked": false},
      {"provider": 2, "provider_label": "alice-gh", "revoked": false}
    ]
  },
  "delegations": [
    {
      "runtime_key": "0x...",
      "expires_at": "1760086400",
      "scope": "messaging"
    }
  ],
  "agents": [
    {
      "endpoint": "https://agent.example.com/api",
      "capabilities": ["chat", "verify", "summarize"]
    }
  ]
}
```

## Check current identity

```bash
vouch --json whoami     # full identity summary (network call)
vouch status            # local config only (no network)
```

## Manage delegations

Create a new runtime key delegation:

```bash
vouch --json delegate --wallet-key 0xKEY --expiry 24h --scope messaging
```

Renew an existing delegation with the same settings:

```bash
vouch --json delegate --wallet-key 0xKEY --renew
```

**Output:**

```json
{
  "runtime_key": "0x...",
  "expires_at": 1760003600,
  "scope": "messaging",
  "tx_hash": "0xdef..."
}
```

Constraints: max 30-day expiry, max 5 delegations per minute.

Revoke a specific key:

```bash
vouch --json revoke-key --wallet-key 0xKEY --key 0xRUNTIME_KEY
```

**Flags:** `--key <address|hex>`, `--expiry <duration>` (default `24h`), `--scope <text>`, `--wallet-key <hex>`, `--renew`

## Publish agent capabilities

Register an endpoint and capabilities in the onchain agent directory:

```bash
vouch --json publish \
  --wallet-key 0xKEY \
  --endpoint https://agent.example.com/api \
  --capabilities "chat,verify,summarize"
```

## Manage trust allowlist

When the allowlist has entries, `vouch verify` and `vouch receive --allowlist` only accept messages from listed agents.

```bash
vouch allowlist add 0xWALLET @alice --note "trusted partner"
vouch allowlist list
vouch allowlist remove @alice
```

## Account and billing

### Check usage

```bash
vouch --json account
```

**Output:**

```json
{
  "period": "2026-02",
  "relay_transactions": 3,
  "relay_limit": 10,
  "tier": "free"
}
```

### List API keys

```bash
vouch --json account keys
```

### Check billing status

```bash
vouch --json account billing
```

### Tier reference

| | Free | Paid (usage-based) |
|---|---|---|
| Verify calls | Unlimited | Free |
| Relay transactions | 10/month | $0.05 each |

Manage billing at https://vouch.directory/dashboard/billing or upgrade via the dashboard.

## Recipes

**Full onboarding for a new agent:**

```bash
vouch init
```

**Sign-then-verify round trip:**

```bash
vouch --json sign --payload '{"action":"deploy"}' \
  | vouch --json verify \
  | jq '{valid, signer, identities}'
```

**Send a verified message to another agent:**

```bash
vouch --json send --payload '{"task":"summarize","doc_id":"abc"}' --url https://agent.example.com/vouch
```

**Agent-to-agent round trip:**

```bash
# Terminal 1: start receiver
vouch receive --port 9090 --handler ./echo.sh

# Terminal 2: send verified message
vouch --json send --payload '{"msg":"hello"}' --url http://localhost:9090/vouch
```

**Scaffold, test, and deploy an agent:**

```bash
vouch agent create
vouch agent start my-agent
# test locally, then deploy:
vouch agent deploy my-agent --prod
vouch publish --wallet-key 0xKEY --endpoint https://my-agent.vercel.app/api/vouch --capabilities "chat,summarize"
```

**Start a receiver with allowlist and rate limiting:**

```bash
vouch receive --port 8080 --handler ./process.sh --allowlist --rate-limit 10
```

**Batch verify from file:**

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

**Check usage before heavy operations:**

```bash
vouch --json account | jq '{relay_transactions, relay_limit, tier}'
```

**Find agents by capability:**

```bash
vouch --json lookup --capability chat | jq '.agents[]'
```

**Link an additional identity after setup:**

```bash
vouch link-github
```

**Sign, send, and verify in a pipeline:**

```bash
SIGNED=$(vouch --json sign --payload '{"task":"deploy","id":"cr-42"}')
echo "$SIGNED" | curl -s -X POST -H "Content-Type: application/json" -d @- https://recipient.example.com/inbox
```

## Reset

Teardown the current identity and reinitialize from scratch:

```bash
vouch reset
```

Interactive mode revokes onchain identity, deletes `~/.vouch/`, then runs the full init flow (requires browser for OAuth). Requires typing `RESET` to confirm.

Skip onchain revocation:

```bash
vouch reset --force
```

Pipe mode (teardown only — reinit requires browser):

```bash
vouch --json reset --wallet-key 0xKEY
```

**Flags:** `--wallet-key <hex>` (enables pipe mode, teardown only), `--force` (skip onchain revocation)

## Teardown

Revoke onchain identity and delete all local state:

```bash
vouch --json teardown --wallet-key 0xKEY
```

Local-only cleanup (skip onchain revocation):

```bash
vouch --json teardown --force
```