Reference

CLI Reference

Complete reference for the SPEND.md command-line interface. Manage wallets, cards, and transactions from your terminal.

Installation

# npm
npm install -g @spend/cli

# yarn
yarn global add @spend/cli

# pnpm
pnpm add -g @spend/cli

Verify installation with spend --version

Authentication

spend login

Authenticate with your SPEND.md account via browser OAuth.

$ spend login

Opening browser for authentication...
✓ Logged in as you@example.com
✓ API key saved to ~/.spend/credentials

spend logout

Remove stored credentials.

$ spend logout

✓ Credentials removed from ~/.spend/credentials

spend whoami

Check current authentication status.

$ spend whoami

Logged in as: you@example.com
Organization: ACME Corp
Plan: Pro
API Key: sk-...7890 (expires: 2026-03-15)

Configuration

spend init

Initialize a new SPEND.md file in the current directory.

$ spend init [options]

Options:
  --name <name>      Agent name (default: directory name)
  --template <type>  Use a template: minimal, standard, full
  --force            Overwrite existing SPEND.md
  
Examples:
  spend init
  spend init --name my-agent --template standard
  spend init --force

spend validate

Validate the SPEND.md file without applying changes.

$ spend validate [file]

Arguments:
  file    Path to SPEND.md file (default: ./SPEND.md)

Examples:
  spend validate
  spend validate ./configs/prod-agent.md

Output:
✓ SPEND.md is valid
  - Identity: my-agent (you@example.com)
  - Monthly limit: $500.00
  - Cards: 1 configured

spend apply

Apply the SPEND.md configuration to create or update the agent wallet.

$ spend apply [options]

Options:
  --file <path>    Path to SPEND.md file
  --dry-run        Show changes without applying
  --yes            Skip confirmation prompts
  
Examples:
  spend apply
  spend apply --dry-run
  spend apply --file ./configs/agent.md --yes

Output:
Validating SPEND.md...
✓ Configuration valid

Changes to apply:
  + Create wallet for "my-agent"
  ~ Update monthly_limit: $100 → $500
  + Add merchant: github.com

Apply changes? [y/N] y
✓ Changes applied successfully

spend diff

Show differences between local SPEND.md and applied configuration.

$ spend diff

--- Applied Configuration
+++ Local SPEND.md

 spend:
-  monthly_limit: 100 USD
+  monthly_limit: 500 USD

 allowlist:
+  - github.com

Card Management

spend card create

Create a new virtual card for the agent.

$ spend card create [options]

Options:
  --name <name>     Card nickname (default: "default")
  --limit <amount>  Override monthly limit for this card
  
Examples:
  spend card create
  spend card create --name "api-card" --limit "100 USD"

Output:
Creating virtual card...
✓ Card created successfully

┌─────────────────────────────────────┐
│  💳 Virtual Card: api-card          │
├─────────────────────────────────────┤
│  Number:   4242 8534 7693 1234      │
│  Exp:      01/28                    │
│  CVV:      847                      │
│  Limit:    $100.00/month            │
└─────────────────────────────────────┘

spend card list

List all cards for the current agent.

$ spend card list

┌──────────────┬────────────────────┬──────────┬───────────┐
│ Name         │ Number             │ Status   │ Limit     │
├──────────────┼────────────────────┼──────────┼───────────┤
│ default      │ •••• •••• •••• 1234│ active   │ $500/mo   │
│ api-card     │ •••• •••• •••• 5678│ active   │ $100/mo   │
│ backup       │ •••• •••• •••• 9012│ frozen   │ $200/mo   │
└──────────────┴────────────────────┴──────────┴───────────┘

spend card show

Show full card details including number and CVV.

$ spend card show <name>

Examples:
  spend card show default
  spend card show api-card

spend card freeze / unfreeze

Temporarily freeze or unfreeze a card. Frozen cards decline all transactions.

$ spend card freeze <name>
✓ Card "api-card" frozen

$ spend card unfreeze <name>
✓ Card "api-card" unfrozen

spend card delete

Permanently delete a card. This action cannot be undone.

$ spend card delete <name> [options]

Options:
  --yes    Skip confirmation prompt

Examples:
  spend card delete backup
  spend card delete backup --yes

Status & Monitoring

spend status

Show current wallet status and spending summary.

$ spend status [options]

Options:
  --json    Output as JSON
  
Output:
┌─────────────────────────────────────┐
│  💳 SPEND.md Status                 │
├─────────────────────────────────────┤
│  Agent:       my-agent              │
│  Balance:     $352.80               │
│  Spent today: $12.50 / $50.00       │
│  Spent month: $147.20 / $500.00     │
│  Cards:       2 active, 1 frozen    │
│  Health:      ✓ All systems normal  │
└─────────────────────────────────────┘

spend balance

Show current balance and earning summary.

$ spend balance

Balance:       $352.80
Earned (MTD):  $420.00
Spent (MTD):   $147.20
Net (MTD):     +$272.80

Pending:       $25.00 (2 transactions)

Transactions

spend transactions

List recent transactions.

$ spend transactions [options]

Options:
  --limit <n>      Number of transactions (default: 20)
  --card <name>    Filter by card
  --status <type>  Filter: completed, declined, pending
  --from <date>    Start date (YYYY-MM-DD)
  --to <date>      End date (YYYY-MM-DD)
  --json           Output as JSON
  --csv            Output as CSV
  
Examples:
  spend transactions
  spend transactions --limit 50 --status completed
  spend transactions --from 2026-01-01 --csv > report.csv

Output:
┌────────────────────┬───────────────┬──────────┬──────────┐
│ Date               │ Merchant      │ Amount   │ Status   │
├────────────────────┼───────────────┼──────────┼──────────┤
│ 2026-01-30 14:23   │ OpenAI        │ $12.50   │ ✓        │
│ 2026-01-30 09:15   │ GitHub        │ $4.00    │ ✓        │
│ 2026-01-29 18:42   │ Anthropic     │ $8.75    │ ✓        │
│ 2026-01-29 11:30   │ Unknown       │ $25.00   │ ✗        │
└────────────────────┴───────────────┴──────────┴──────────┘

spend transactions show

Show details for a specific transaction.

$ spend transactions show <id>

Transaction: txn_abc123
────────────────────────────
Date:       2026-01-30 14:23:45 UTC
Merchant:   OpenAI
Amount:     $12.50 USD
Card:       default (•••• 1234)
Status:     Completed
Category:   api_services

Metadata:
  IP:       10.0.1.50
  Agent:    my-agent v2.1
  Request:  req_xyz789

Approvals

spend approvals

List pending approval requests.

$ spend approvals

Pending Approvals:
──────────────────────────────────────────────────────
ID: apr_123
  Merchant: AWS
  Amount:   $75.00
  Reason:   Exceeds auto-approve limit ($25)
  Expires:  14 minutes

ID: apr_456
  Merchant: Twilio
  Amount:   $150.00
  Reason:   Requires confirmation (>$100)
  Expires:  28 minutes
──────────────────────────────────────────────────────

Run: spend approve <id> or spend deny <id>

spend approve / deny

Approve or deny a pending transaction.

$ spend approve <id> [options]
$ spend deny <id> [options]

Options:
  --reason <text>    Add a reason (required for deny)
  
Examples:
  spend approve apr_123
  spend deny apr_456 --reason "Unexpected expense"

Output:
✓ Transaction apr_123 approved
  Merchant: AWS
  Amount:   $75.00

Configuration Commands

spend config

View or modify CLI configuration.

$ spend config [key] [value]

# View all config
$ spend config

# View specific key
$ spend config default_currency

# Set value
$ spend config default_currency EUR

Available keys:
  default_currency    Default currency for display
  output_format       Default output format (table, json)
  color               Enable/disable colors (auto, always, never)

spend export

Export transactions or configuration.

$ spend export <type> [options]

Types:
  transactions    Export transaction history
  config          Export current configuration

Options:
  --format <fmt>  Output format: json, csv, yaml
  --from <date>   Start date for transactions
  --to <date>     End date for transactions
  --output <file> Write to file instead of stdout
  
Examples:
  spend export transactions --format csv --output report.csv
  spend export config --format yaml

Environment Variables

The CLI can be configured via environment variables:

VariableDescription
SPEND_API_KEYAPI key for authentication (overrides stored credentials)
SPEND_API_URLAPI base URL (for self-hosted instances)
SPEND_CONFIG_DIROverride config directory (default: ~/.spend)
SPEND_NO_COLORDisable colored output
SPEND_DEBUGEnable debug logging

Global Flags

These flags work with all commands:

--help, -h       Show help for a command
--version, -v    Show CLI version
--quiet, -q      Suppress non-error output
--verbose        Enable verbose output
--json           Output as JSON (where supported)
--no-color       Disable colored output
--config <path>  Use custom config file