@visa/cli 2.0.0-rc.6 → 2.0.0-rc.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +62 -26
  2. package/dist/cli.js +182 -129
  3. package/dist/mcp-server/index.js +38 -61
  4. package/install.ps1 +36 -5
  5. package/package.json +6 -4
package/README.md CHANGED
@@ -31,7 +31,15 @@ Add to your MCP client config:
31
31
  }
32
32
  ```
33
33
 
34
- 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.
34
+ 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.
35
+
36
+ ## Enable the spend HUD (recommended)
37
+
38
+ Keep an eye on what your agents are spending. The HUD shows your balance, active card, and recent tool usage on every prompt.
39
+
40
+ ```bash
41
+ visa-cli config hud enable
42
+ ```
35
43
 
36
44
  ---
37
45
 
@@ -41,13 +49,21 @@ Once connected, your assistant will have access to all payment tools. The first
41
49
  visa-cli login # GitHub OAuth — opens browser, stores session token
42
50
  visa-cli add-card # Enroll a Visa card via VGS secure form
43
51
  visa-cli status # Show auth state, enrolled cards, daily spend remaining
44
- visa-cli api-key create my-demo-app
45
- # Create an API key for an app or agent
46
- visa-cli history # Recent transactions with amounts and any generated media URLs
47
- visa-cli hud enable # Explicitly pin the Visa HUD below Claude Code input
48
- visa-cli hud disable # Remove the Visa HUD from Claude Code
49
- visa-cli statusline # Render the multi-line HUD Claude Code calls automatically
50
- visa-cli mcp # Start the MCP server
52
+ visa-cli tokens create my-demo-app
53
+ # Create an API token for an app or agent
54
+ visa-cli history # Recent transactions with amounts and status
55
+ visa-cli config hud enable
56
+ # Enable the terminal HUD for Codex and regular shells
57
+ visa-cli config hud doctor
58
+ # Diagnose terminal HUD setup
59
+ visa-cli config hud disable
60
+ # Remove the terminal HUD from your shell
61
+ visa-cli config hud enable claude
62
+ # Legacy: register the Claude Code statusLine renderer
63
+ visa-cli config statusline
64
+ # Renderer for statusLine integrations
65
+ # MCP (stdio): run the bundled entrypoint (IDE configs use the same path — see getServerEntry in src/clients.ts)
66
+ # node "$(npm root -g)/@visa/cli/dist/mcp-server/index.js"
51
67
  ```
52
68
 
53
69
  ---
@@ -65,7 +81,7 @@ visa-cli status # verify you're logged in
65
81
 
66
82
  ## Card enrollment
67
83
 
68
- Cards are tokenized via VGS — your raw card number never touches Visa servers. `add_card` opens a hosted VGS Collect form in your browser.
84
+ 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.
69
85
 
70
86
  ```bash
71
87
  visa-cli add-card
@@ -75,10 +91,22 @@ Multiple cards can be enrolled. The first becomes the default; you can switch de
75
91
 
76
92
  ---
77
93
 
94
+ ## Credits & referrals
95
+
96
+ 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.
97
+
98
+ 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.
99
+
100
+ Share your referral link (visible in `get_status`) and you both get **$2 in free credits** when your referral enrolls a card.
101
+
102
+ ---
103
+
78
104
  ## Payments & Authentication
79
105
 
80
106
  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.
81
107
 
108
+ 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.
109
+
82
110
  You can set hard limits via the `update_spending_controls` tool, or check your current limits any time:
83
111
 
84
112
  ```bash
@@ -87,14 +115,14 @@ visa-cli status
87
115
 
88
116
  ---
89
117
 
90
- ## API keys for apps and agents
118
+ ## API tokens for apps and agents
91
119
 
92
- Approved users can create API keys from the CLI with their existing login:
120
+ Approved users can create API tokens from the CLI with their existing login:
93
121
 
94
122
  ```bash
95
- visa-cli api-key create my-demo-app --tools generate_image_card,run_llm --daily-cap 5
96
- visa-cli api-key list
97
- visa-cli api-key revoke 1
123
+ visa-cli tokens create my-demo-app --tools generate_image_card,run_llm --daily-cap 5
124
+ visa-cli tokens list
125
+ visa-cli tokens revoke 1
98
126
  ```
99
127
 
100
128
  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 +141,11 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
113
141
  | `remove_card` | Remove an enrolled card (authentication required) |
114
142
  | `set_default_card` | Change the default card (authentication required) |
115
143
  | `get_status` | Auth, card, spend limits, and budget summary |
144
+ | `start_session` | Start a capped approval window for paid tools in this MCP process |
145
+ | `get_session_status` | Show the active session cap, estimated spend, and remaining amount |
146
+ | `close_session` | Close the active session and return to pay-as-you-go approvals |
116
147
  | `update_spending_controls` | Set daily and per-transaction limits (authentication required) |
117
- | `transaction_history` | Recent transactions with amounts and media URLs |
148
+ | `transaction_history` | Recent transactions with amounts, merchants, status, and support IDs |
118
149
  | `feedback` | Submit feedback on a tool result |
119
150
  | `reset` | Clear auth state and credentials |
120
151
 
@@ -122,11 +153,9 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
122
153
 
123
154
  | Tool | Price | Description |
124
155
  |------|-------|-------------|
125
- | `generate_image_card` | ~$0.06 | FLUX1.1 Ultra — 2K resolution, ~30s |
126
- | `generate_image_fast_card` | ~$0.04 | FLUX1.1 Pro — 1K resolution, ~10s |
127
- | `generate_video` | $0.10–$0.30 | Text-to-video (Wan / MiniMax / Kling) |
128
- | `generate_music_tempo_card` | ~$0.10 | Suno AI music generation, ~2 min |
129
- | `check_music_status_tempo_card` | ~$0.01 | Poll Suno task for audio URL |
156
+ | `generate_image` | $0.01–$0.08 | Curated image generation tiers |
157
+ | `generate_video` | $0.10–$0.20 | Text-to-video (Wan / MiniMax / Kling) |
158
+ | `generate_music` | ~$0.10 | Suno AI music generation, ~60–90s |
130
159
  | `generate_audio` | ~$0.03–$0.04 | TTS (MetaVoice) or SFX (Stable Audio) |
131
160
  | `generate_3d` | ~$0.08 | Text-to-3D mesh (Trellis), returns GLB URL |
132
161
  | `upscale_image` | ~$0.03 | Image upscaling (Aura SR) |
@@ -136,16 +165,13 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
136
165
 
137
166
  | Tool | Price | Description |
138
167
  |------|-------|-------------|
139
- | `query_onchain_prices_card` | ~$0.02 | Real-time or historical token prices (150+ chains via Allium) |
140
- | `allium_explorer_card` | ~$0.10 | Natural language → SQL blockchain query (step 1) |
141
- | `allium_explorer_results_card` | up to $3.00 | Fetch results for a submitted query (step 2) |
142
168
  | `run_llm` | $0.01–$0.09 | Run a prompt through GPT-4o Mini, Claude, DeepSeek, Perplexity, or Llama |
169
+ | `get_visa_smi` | $0.10 | Visa Spending Momentum Index by US state + county (early access — request access) |
143
170
 
144
171
  ### Utility
145
172
 
146
173
  | Tool | Description |
147
174
  |------|-------------|
148
- | `pay` | Generic HTTP 402 payment endpoint |
149
175
  | `batch` | Execute multiple paid tools in one authentication approval |
150
176
  | `discover_tools` | Search the dynamic tool catalog |
151
177
  | `execute_tool` | Run a tool from the dynamic catalog by ID |
@@ -171,6 +197,16 @@ Max per-transaction — hard cap per single tool call
171
197
 
172
198
  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.
173
199
 
200
+ ## Sessions
201
+
202
+ Paid tools are pay-as-you-go by default: each paid call requests payment approval. To approve a capped window for the current MCP process, use `start_session`:
203
+
204
+ ```bash
205
+ start_session capUsd=5
206
+ ```
207
+
208
+ Paid calls then spend from that approval window until the cap is used, `close_session` is called, the session expires, or the MCP process restarts. Sessions are not reused across Claude/MCP restarts.
209
+
174
210
  ---
175
211
 
176
212
  ## Config & data locations
@@ -186,7 +222,7 @@ Both limits are enforced server-side. Authentication is always required per paym
186
222
  ## Troubleshooting
187
223
 
188
224
  **Touch ID prompt doesn't appear (macOS)**
189
- 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.
225
+ 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.
190
226
 
191
227
  **"Not logged in" after `visa-cli login`**
192
228
  Restart the MCP server after logging in — your MCP client needs to reconnect to pick up the new session.
@@ -204,4 +240,4 @@ Delete `~/.visa-mcp/catalog-cache.json` and restart the MCP server to force a fr
204
240
 
205
241
  ## Monorepo context
206
242
 
207
- 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).
243
+ 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).