agenzo-token-cli

CLI tool for AI Agents to manage payment tokens — VCN, Network Token, and X402. Built for humans and AI Agents, with interactive prompts, 3DS-verified payment methods, and multi-developer API key management.

Install · AI Agent Skill · Quick Start · Commands · Auth · Contributing

Why agenzo-token-cli?

• Agent-Native Design — Structured SKILL.md out of the box, AI Agents can operate payment flows with zero extra setup
• Three Token Types — VCN (virtual cards), Network Token (cryptogram-based), X402 (on-chain signatures)
• Interactive & Scriptable — Smart prompts with card selection UI, or pass all flags for automation
• Secure by Default — CVV masked input (or --cvv flag for automation), OS-native credential storage, 3DS verification
• Multi-Developer — One org, multiple developers, scoped API keys

Features

Category	Capabilities
🔐 Auth	Magic Link login, auto-registration, token refresh, multi-org switch
👤 Developers	Create, list, get, update developers under your organization
🔑 API Keys	Create, list, rotate, disable keys scoped to each developer
💳 Payment Methods	Add payment methods with 3DS (default mode) or via DropIn SDK (drop-in mode), verification polling, --cvv flag for automation, duplicate card override
🎫 VCN	Virtual card with spend limit, backed by AgentCard + Evo preauth
🔒 Network Token	Cryptogram via evo-cli, supports Visa & MasterCard (issuer-dependent)
⛓️ X402	On-chain payment signature for Web3 transactions
⚙️ Config	Set API host, view config, reset to defaults

Installation

npm install -g agenzo-token-cli

Requirements: Node.js 18+

Version compatibility

The server advertises the minimum required CLI version via the X-CLI-Min-Version response header. If your installed CLI is below that minimum, any command refuses to run and exits with code 2:

✗ CLI 1.2.0 is below the required minimum 1.3.0.
ℹ Upgrade: npm install -g agenzo-token-cli@latest

Run the upgrade command and retry. The floor is controlled server-side (AGENT_PAY_CLI_MIN_VERSION env var), so raising it does not require a CLI release.

AI Agent Skill

This CLI ships with a structured SKILL.md that AI Agents can use to understand and operate all payment flows. The skill covers:

• Complete onboarding flow (login → developer → key → card → token)
• All command signatures and parameters
• Token type compatibility rules
• Common errors and fixes

To use with your AI Agent, include SKILL.md in the agent's context or tool definition.

Quick Start

For Humans

# 1. Sign in (auto-registers on first use)
agenzo-token-cli login --email [email protected]

# 2. Create a developer
agenzo-token-cli developers create --developer-name "My Agent" --developer-email [email protected]

# 3. Create an API Key (save it — only shown once!)
agenzo-token-cli keys create --developer-id dev_01KPX... --key-name "Production Key"

# 4. Add a payment method (interactive 3DS verification)
agenzo-token-cli payment-methods add --api-key sk_prod_xxx --email [email protected]

# Or pass all card details for automation (CVV via flag)
agenzo-token-cli payment-methods add --api-key sk_prod_xxx --email [email protected] --card-number 2223001870064586 --expiry 1226 --cvv 935

# Or use Drop-in mode (card details entered in your own front-end via Evo DropIn SDK)
agenzo-token-cli payment-methods add --mode dropin --api-key sk_prod_xxx --email [email protected]

# 5. Create a payment token (interactive card selection)
# --idempotency-key is required and must be supplied by the caller; the CLI prompts if omitted.
agenzo-token-cli payment-tokens create --type vcn --api-key sk_prod_xxx --idempotency-key idem_001
agenzo-token-cli payment-tokens create --type network-token --api-key sk_prod_xxx --idempotency-key idem_002
agenzo-token-cli payment-tokens create --type x402 --api-key sk_prod_xxx --idempotency-key idem_003

# Or specify card directly (matches by last 4 digits, skips selection)
agenzo-token-cli payment-tokens create --type network-token --api-key sk_prod_xxx --card 5204731620064587 --idempotency-key idem_004

For AI Agents

Read SKILL.md for the complete guide. Key points:

1. All Runtime Plane commands require --api-key (the full sk_prod_... string)
2. API keys are scoped to a developer — cards added with Key A are not visible to Key B
3. payment-tokens create auto-fetches the card list and prompts for selection
4. Not all cards support Network Token — check evo_data.network_token after the payment method is added

Commands

Command	Description
login	Sign in via Magic Link (auto-registers on first use)
logout	Sign out of current organization
orgs me / update / list / switch	Organization management
developers create / list / get / update	Developer management
keys create / list / get / rotate / disable	API Key management
payment-methods add / list / get / disable	Add payment methods with 3DS verification
payment-tokens create / list / get / revoke	Payment tokens (VCN / Network Token / X402)
config set-host / reset-host / show	API host configuration

Command Reference

Organization Management

agenzo-token-cli orgs me                              # View current org
agenzo-token-cli orgs list                            # List all signed-in orgs
agenzo-token-cli orgs switch <org_id>                 # Switch active org
agenzo-token-cli orgs update --name "New Org Name"    # Update org name
agenzo-token-cli orgs update --email [email protected]  # Update org email (requires verification)

Developer Management

agenzo-token-cli developers create --developer-name "My Agent" --developer-email [email protected]
agenzo-token-cli developers list
agenzo-token-cli developers get <developer_id>
agenzo-token-cli developers update <developer_id> --name "New Name"
agenzo-token-cli developers update <developer_id> --email [email protected]

API Key Management

agenzo-token-cli keys create --developer-id <dev_id> --key-name "Prod Key"
agenzo-token-cli keys list --developer-id <dev_id>
agenzo-token-cli keys get <key_id>
agenzo-token-cli keys rotate <key_id>     # Generate new key value (old one invalidated)
agenzo-token-cli keys disable <key_id>    # Permanently disable key

Payment Method Management

# Default mode (CLI collects card details, 3DS via email)
agenzo-token-cli payment-methods add --api-key <key>
agenzo-token-cli payment-methods add --api-key <key> --email [email protected] --card-number 2223001870064586 --expiry 1226 --cvv 935

# Drop-in mode (add payment method via DropIn SDK in agent's front-end)
agenzo-token-cli payment-methods add --mode dropin --api-key <key> --email [email protected]

agenzo-token-cli payment-methods list --api-key <key>
agenzo-token-cli payment-methods get <pm_id> --api-key <key>
agenzo-token-cli payment-methods disable <pm_id> --api-key <key>

Payment Token Management

# Interactive mode (prompts for type, amount, etc.)
agenzo-token-cli payment-tokens create --api-key <key>

# Full-flag mode (for automation / AI Agents)
# --idempotency-key is required and must be supplied by the caller; the CLI prompts if omitted (it never auto-generates one).
agenzo-token-cli --yes payment-tokens create --type vcn --api-key <key> --card 2223001870064586 --amount 30 --idempotency-key idem_001
agenzo-token-cli --yes payment-tokens create --type network-token --api-key <key> --card 2223001870064586 --idempotency-key idem_002
agenzo-token-cli --yes payment-tokens create --type x402 --api-key <key> --payment-method-id <pm_id> --pay-to 0xABC... --amount 1000000 --nonce abc123 --network base_sepolia --deadline 1777457396 --idempotency-key idem_003

# Query and revoke
agenzo-token-cli payment-tokens list --api-key <key>
agenzo-token-cli payment-tokens get <ptk_id> --api-key <key>
agenzo-token-cli payment-tokens revoke <ptk_id> --api-key <key>

Configuration

agenzo-token-cli config set-host http://localhost:8000  # Set API host (local dev)
agenzo-token-cli config reset-host                      # Reset to default
agenzo-token-cli config show                            # Show current config

Authentication

Plane	Commands	Auth Method
Control Plane	orgs, developers, keys	Bearer Token (via login)
Runtime Plane	payment-methods, payment-tokens	API Key (--api-key flag)

Project Structure

├── SKILL.md               # AI Agent skill definition
├── src/
│   ├── auth/              # Login/logout + AuthService
│   ├── orgs/              # Organization management
│   ├── developers/        # Developer management
│   ├── keys/              # API Key management
│   ├── payment-methods/   # Add payment methods + 3DS
│   ├── payment-tokens/    # VCN / Network Token / X402
│   ├── api/               # HTTP client
│   ├── config/            # Local config & credentials
│   ├── utils/             # Formatting, prompts, errors
│   └── types/             # TypeScript type definitions

Development

npm install        # Install dependencies
npm run dev        # Dev build (watch)
npm test           # Run tests
npm run build      # Production build

License

MIT