@payllm/cli

Command-line interface for PayLLM — virtual Mastercards for autonomous agent spending. Lets humans and agents create, fund, reveal, and manage cards from the terminal.

API-key lifecycle and spending-limit changes are dashboard-only and intentionally absent from this CLI.

Install

npm install -g @payllm/cli
payllm --version

Quick start

# 1. Authenticate (opens the PayLLM dashboard in your browser)
payllm login

# 2. Verify KYC
payllm kyc status

# 3. Reserve a card
payllm cards create --nickname "groceries" --amount 20

# 4. Watch the deposit land and auto-activate the card
payllm deposit watch <card-id>

# 5. Reveal the card credentials (opens the PCI-scoped reveal page)
payllm cards reveal <card-id>

Global flags

Flag | Env var | Notes ---|---|--- --creds-file <path> | PAYLLM_CREDS_FILE | override ~/.payllm/credentials --json | — | machine-readable JSON output

Commands

payllm login [--force]          Authenticate via browser handshake
payllm logout                   Clear local credentials
payllm whoami                   Show the authenticated account
payllm config                   Show auth state + creds file

payllm kyc status               Current KYC state
payllm kyc start                Open a KYC session in the dashboard
payllm kyc wait [--timeout N]   Block until KYC clears

payllm cards list
payllm cards get <id>
payllm cards create [--nickname N] [--amount $X] [--type usd|gold] [--wait]
payllm cards freeze <id>
payllm cards unfreeze <id>
payllm cards rename <id> "<nickname>"
payllm cards close <id> [--yes]
payllm cards reveal <id>        Open the PCI-scoped reveal page in the browser

payllm deposit address [card-id]
payllm deposit list [card-id]
payllm deposit watch <card-id> [--timeout N]

payllm balance [card-id]
payllm transactions <card-id> [--page N]
payllm activity [--page N]
payllm withdraw <card-id> --amount $X [--asset USDT|USDC|XAUT]

payllm browse detect --url <url>                       Inspect a checkout form
payllm browse fill   <card-id> --url <url>             Fill card fields, no submit
payllm browse pay    <card-id> --url <url>             Fill + submit a checkout

Dashboard-only actions

The following actions are not exposed through the CLI. They live only in the PayLLM dashboard at https://payllm.ai:

• Issuing, rotating, or revoking API keys
• Viewing or changing the daily spending limit
• Updating the withdrawal address and other account settings

If a command you expect is missing, check the dashboard.

Headless checkout (browse)

browse commands run a real headless Chromium inside the CLI process. No visible browser window is opened unless you pass --no-headless for debugging. First-time setup:

npx playwright install chromium

Flags common to browse pay and browse fill:

Flag | Meaning ---|--- --url <url> | merchant checkout URL (required) --email <x> | override the email on file from KYC --no-submit | fill only, never click the submit button --no-headless | show the browser window (debug only) --timeout <seconds> | navigation timeout (default 30) --screenshot <path> | save a full-page PNG after fill / submit

browse pay reports a single status field — see the Status codes table below.

Status codes returned by browse pay

| Status | Meaning | Did the card get charged? | |---|---|---| | success | Affirmative success signal seen (redirect to /success, "thank you" text, etc.) | Yes — verify with payllm transactions <card-id> | | error | Merchant reported a failure (declined, 3DS failed, etc.) | No | | pending | Submit clicked, no success/error signal within the outcome timeout | Unknown — do not assume success. Verify with payllm transactions <card-id> after 30–60s | | submit_failed | Submit button not found or stayed disabled | No | | filled | --no-submit was passed; fields filled only | No | | no_form | Checkout form not detected on the page | No |

Only success means the payment definitely went through. Everything else requires explicit verification.

Credentials

The cp_ API key lives at ~/.payllm/credentials with 0600 perms after payllm login. The CLI reads it on every invocation. Use payllm logout to clear it locally. To revoke a key server-side, use the PayLLM dashboard.

Architecture

src/
├── lib/              # Pure TypeScript HTTP client + config + types
│   ├── client.ts     # PayllmClient
│   ├── config.ts     # config resolution + creds file I/O
│   └── types.ts      # shared response shapes
└── cli/
    ├── index.ts      # commander entry
    ├── helpers.ts    # auth-aware client factory + pretty printers
    └── commands/     # one file per command group

The lib/ module is exported from the package so downstream tooling (e.g. an MCP server) can import the client directly instead of shelling out to the CLI.