@visa/cli 2.0.0-rc.9 → 2.0.1-rc.0

package/README.md

@@ -6,13 +6,17 @@ AI-powered payments over MCP. Exposes Visa card payment tools as MCP (Model Cont
 
 | Platform | Credential Storage | Payment Auth | Install |
 |----------|-------------------|--------------|---------|
-| **macOS** | Keychain | Touch ID / Secure Enclave | `bash <(curl -fsSL ...)` or `npm i -g @visa/cli` |
-| **Windows** | ACL-restricted file | Server-verified (restricted limits) | `npm i -g @visa/cli` or `iwr -useb https://visacli.sh/install.ps1 | iex` |
-| **Linux** | libsecret (GNOME Keyring / KDE Wallet) | Server-verified (restricted limits) | `bash <(curl -fsSL ...)` or `npm i -g @visa/cli` |
+| **macOS** | Keychain | Touch ID / Secure Enclave | `bash <(curl -fsSL https://visacli.sh/install.sh)` or `npm i -g @visa/cli` |
+| **Windows** | ACL-restricted file | Server-verified (restricted limits) | `npm i -g @visa/cli` or `iwr -useb https://visacli.sh/install.ps1 \| iex` |
+| **Linux** | libsecret (GNOME Keyring / KDE Wallet) | Server-verified (restricted limits) | `bash <(curl -fsSL https://visacli.sh/install.sh)` or `npm i -g @visa/cli` |
 
 ## Install
 
 ```bash
+# one-liner (installs Node.js check + npm install + verification)
+bash <(curl -fsSL https://visacli.sh/install.sh)
+
+# or directly via npm
 npm install -g @visa/cli
 ```
 
@@ -31,7 +35,15 @@ Add to your MCP client config:
 }
 ```
 
-Once connected, your assistant will have access to all payment tools. The first time you use a paid tool, you'll be prompted to log in and enroll a card.
+Once connected, your assistant will have access to all payment tools. The first time you use a paid tool, you'll be prompted to log in and enroll a card — you'll get $1 in free credits to start.
+
+## Enable the spend HUD (recommended)
+
+Keep an eye on what your agents are spending. The HUD shows your balance, active card, and recent tool usage on every prompt.
+
+```bash
+visa-cli config hud enable
+```
 
 ---
 
@@ -41,13 +53,21 @@ Once connected, your assistant will have access to all payment tools. The first
 visa-cli login        # GitHub OAuth — opens browser, stores session token
 visa-cli add-card     # Enroll a Visa card via VGS secure form
 visa-cli status       # Show auth state, enrolled cards, daily spend remaining
-visa-cli api-key create my-demo-app
-                      # Create an API key for an app or agent
-visa-cli history      # Recent transactions with amounts and any generated media URLs
-visa-cli hud enable   # Explicitly pin the Visa HUD below Claude Code input
-visa-cli hud disable  # Remove the Visa HUD from Claude Code
-visa-cli statusline   # Render the multi-line HUD Claude Code calls automatically
-visa-cli mcp          # Start the MCP server
+visa-cli tokens create my-demo-app
+                      # Create an API token for an app or agent
+visa-cli history      # Recent transactions with amounts and status
+visa-cli config hud enable
+                      # Enable the terminal HUD for Codex and regular shells
+visa-cli config hud doctor
+                      # Diagnose terminal HUD setup
+visa-cli config hud disable
+                      # Remove the terminal HUD from your shell
+visa-cli config hud enable claude
+                      # Legacy: register the Claude Code statusLine renderer
+visa-cli config statusline
+                      # Renderer for statusLine integrations
+# MCP (stdio): run the bundled entrypoint (IDE configs use the same path — see getServerEntry in src/clients.ts)
+#   node "$(npm root -g)/@visa/cli/dist/mcp-server/index.js"
 ```
 
 ---
@@ -65,7 +85,7 @@ visa-cli status   # verify you're logged in
 
 ## Card enrollment
 
-Cards are tokenized via VGS — your raw card number never touches Visa servers. `add_card` opens a hosted VGS Collect form in your browser.
+Cards are tokenized via VGS — your raw card number never touches Visa servers. `add_card` opens a hosted VGS Collect form in your browser. You receive $1 in free credits on your first card enrollment.
 
 ```bash
 visa-cli add-card
@@ -75,10 +95,22 @@ Multiple cards can be enrolled. The first becomes the default; you can switch de
 
 ---
 
+## Credits & referrals
+
+You receive **$1 in free credits** when you enroll your first card — enough for about 16 AI images. Credits are used automatically before your card is charged.
+
+To add more credits from the CLI, run `visa-cli balance topup --amount 5`. In MCP clients, the equivalent tool is `buy_credits`. Both names refer to the same card-funded wallet top-up path and are subject to the same spending controls.
+
+Share your referral link (visible in `get_status`) and you both get **$2 in free credits** when your referral enrolls a card.
+
+---
+
 ## Payments & Authentication
 
 Every paid tool call requires authentication. On macOS, this is Touch ID (or device password); on Windows and Linux, payments are server-verified with restricted spending limits. Your assistant will show you the amount and merchant before prompting. If you cancel, the payment is aborted — nothing is charged.
 
+Remote CLI/MCP servers can run ordinary paid tools under those server-enforced limits, but card-funded credit top-ups require local biometric attestation. Credits and the biometric preference are account-level: top up from any interactive Touch ID-capable CLI signed into the same account, optionally run `visa-cli biometric off` there for remote ordinary payments, then use that balance from the remote server. Credit top-ups still require local attestation even when biometric is off. For unattended server workloads, scoped API keys with daily caps are also supported.
+
 You can set hard limits via the `update_spending_controls` tool, or check your current limits any time:
 
 ```bash
@@ -87,14 +119,14 @@ visa-cli status
 
 ---
 
-## API keys for apps and agents
+## API tokens for apps and agents
 
-Approved users can create API keys from the CLI with their existing login:
+Approved users can create API tokens from the CLI with their existing login:
 
 ```bash
-visa-cli api-key create my-demo-app --tools generate_image_card,run_llm --daily-cap 5
-visa-cli api-key list
-visa-cli api-key revoke 1
+visa-cli tokens create my-demo-app --tools generate_image_card,run_llm --daily-cap 5
+visa-cli tokens list
+visa-cli tokens revoke 1
 ```
 
 The create command prints the raw `vk_...` key once. Store it in your app or agent secret store and send it as `X-Api-Key` to `/v1/api/shortcuts/:tool`.
@@ -113,8 +145,11 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
 | `remove_card` | Remove an enrolled card (authentication required) |
 | `set_default_card` | Change the default card (authentication required) |
 | `get_status` | Auth, card, spend limits, and budget summary |
+| `start_session` | Start a capped approval window for paid tools in this MCP process |
+| `get_session_status` | Show the active session cap, estimated spend, and remaining amount |
+| `close_session` | Close the active session and return to pay-as-you-go approvals |
 | `update_spending_controls` | Set daily and per-transaction limits (authentication required) |
-| `transaction_history` | Recent transactions with amounts and media URLs |
+| `transaction_history` | Recent transactions with amounts, merchants, status, and support IDs |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear auth state and credentials |
 
@@ -122,11 +157,9 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
 
 | Tool | Price | Description |
 |------|-------|-------------|
-| `generate_image_card` | ~$0.06 | FLUX1.1 Ultra — 2K resolution, ~30s |
-| `generate_image_fast_card` | ~$0.04 | FLUX1.1 Pro — 1K resolution, ~10s |
-| `generate_video` | $0.10–$0.30 | Text-to-video (Wan / MiniMax / Kling) |
-| `generate_music_tempo_card` | ~$0.10 | Suno AI music generation, ~2 min |
-| `check_music_status_tempo_card` | ~$0.01 | Poll Suno task for audio URL |
+| `generate_image` | $0.01–$0.08 | Curated image generation tiers |
+| `generate_video` | $0.10–$0.20 | Text-to-video (Wan / MiniMax / Kling) |
+| `generate_music` | ~$0.02 | Prompt-to-music tracks (ACE-Step) |
 | `generate_audio` | ~$0.03–$0.04 | TTS (MetaVoice) or SFX (Stable Audio) |
 | `generate_3d` | ~$0.08 | Text-to-3D mesh (Trellis), returns GLB URL |
 | `upscale_image` | ~$0.03 | Image upscaling (Aura SR) |
@@ -136,16 +169,13 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
 
 | Tool | Price | Description |
 |------|-------|-------------|
-| `query_onchain_prices_card` | ~$0.02 | Real-time or historical token prices (150+ chains via Allium) |
-| `allium_explorer_card` | ~$0.10 | Natural language → SQL blockchain query (step 1) |
-| `allium_explorer_results_card` | up to $3.00 | Fetch results for a submitted query (step 2) |
 | `run_llm` | $0.01–$0.09 | Run a prompt through GPT-4o Mini, Claude, DeepSeek, Perplexity, or Llama |
+| `get_visa_smi` | $0.10 | Visa Spending Momentum Index by US state + county (early access — request access) |
 
 ### Utility
 
 | Tool | Description |
 |------|-------------|
-| `pay` | Generic HTTP 402 payment endpoint |
 | `batch` | Execute multiple paid tools in one authentication approval |
 | `discover_tools` | Search the dynamic tool catalog |
 | `execute_tool` | Run a tool from the dynamic catalog by ID |
@@ -171,6 +201,18 @@ Max per-transaction — hard cap per single tool call
 
 Both limits are enforced server-side. Authentication is always required per payment regardless of limits — this cannot be disabled. On macOS this means Touch ID; on other platforms, server-side verification with restricted spending limits applies.
 
+## Sessions
+
+Paid tools are pay-as-you-go by default: each paid call opens a one-shot session, requests payment approval, runs the call, and closes that one-shot session. Receipts still include a session id in pay-as-you-go mode.
+
+To approve a reusable capped window for the current MCP process, use `start_session`:
+
+```bash
+start_session capUsd=5
+```
+
+Paid calls then spend from that explicit approval window until the cap is used, `close_session` is called, the window expires, or the MCP process restarts. After `close_session`, paid calls return to pay-as-you-go one-shot sessions. Explicit approval windows are not reused across Claude/MCP restarts.
+
 ---
 
 ## Config & data locations
@@ -186,7 +228,7 @@ Both limits are enforced server-side. Authentication is always required per paym
 ## Troubleshooting
 
 **Touch ID prompt doesn't appear (macOS)**
-Make sure `visa-cli mcp` is running as a foreground process that has access to the macOS security framework. Running inside some sandboxed environments may prevent Touch ID. On Windows and Linux, biometric prompts are not used — payments are server-verified.
+Make sure the MCP process (`node …/dist/mcp-server/index.js`) runs in a foreground TTY with access to the macOS security framework. Running inside some sandboxed environments may prevent Touch ID. On Windows and Linux, biometric prompts are not used for ordinary payments. Buying credits with an enrolled card currently requires local biometric attestation from the CLI; remote servers can spend account balance topped up from any interactive Touch ID-capable CLI signed into the same account.
 
 **"Not logged in" after `visa-cli login`**
 Restart the MCP server after logging in — your MCP client needs to reconnect to pick up the new session.
@@ -204,4 +246,4 @@ Delete `~/.visa-mcp/catalog-cache.json` and restart the MCP server to force a fr
 
 ## Monorepo context
 
-Request routing (MCP vs MPP vs Studio): [docs/agents/ARCHITECTURE.md](../../docs/agents/ARCHITECTURE.md). Branches and deploy: [docs/agents/PIPELINE.md](../../docs/agents/PIPELINE.md). Contributor workflow: [AGENTS.md](../../AGENTS.md), doc index: [docs/agents/README.md](../../docs/agents/README.md).
+Request routing (MCP vs MPP vs web): [docs/agents/ARCHITECTURE.md](../../docs/agents/ARCHITECTURE.md). Branches and deploy: [docs/agents/PIPELINE.md](../../docs/agents/PIPELINE.md). Contributor workflow: [AGENTS.md](../../AGENTS.md), doc index: [docs/agents/README.md](../../docs/agents/README.md).