# Getting Started

# Getting Started

Visa CLI gives your AI agent a Visa-backed payment tool. Your agent can use paid tools for images, video, music, models, search, and other online purchases, but every paid action requires your authorization before money moves.

Your card number is not stored on your machine. Card entry happens in a secure browser flow, card tokens live server-side in an encrypted vault, and default spending limits are enforced server-side.

> **Account access.** Visa CLI is available to approved accounts. New users can start setup from the web or CLI and finish card enrollment in the secure browser flow.
>
> **Works with MCP clients.** Use it with Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Cline, Roo Code, VS Code Copilot, Zed, or another MCP-compatible client.
>
> **Platform support.** macOS is the primary path. Windows supports setup and restricted server-verified payments. Linux support is limited. Node.js 18+ is required.

## Requirements

- Node.js 18+ and npm
- An MCP-compatible AI client
- A GitHub account for sign-in
- A payment card for the secure enrollment flow

Check Node and npm:

```bash
node --version
npm --version
```

If Node is older than 18 or npm is missing, install Node.js from [nodejs.org](https://nodejs.org), then reopen your terminal.

## Install

macOS and Linux:

```bash
curl -fsSL https://app.visacli.sh/cli | bash
```

Windows PowerShell:

```powershell
iwr -useb https://app.visacli.sh/install.ps1 | iex
```

The installer continues into `visa-cli setup` when run from an interactive terminal. Setup opens a browser window. Sign in with GitHub, then add your card through the secure enrollment page. New users receive $1 in free credits on first card enrollment.

If the installer cannot run setup because the terminal is non-interactive, it prints the follow-up command:

```bash
visa-cli setup
```

## Connect Your Agent

Add Visa CLI as an MCP server in your client. The easiest way is to let the CLI write the config for you:

```bash
visa-cli install claude   # or: cursor, windsurf, cline, codex, zed, ...
```

To configure manually, point the client at the bundled server entrypoint. Replace `<npm root -g>` with the output of `npm root -g`:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Codex TOML:

```toml
[mcp_servers.visa-cli]
command = "node"
args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
```

Claude Code users can reconnect an already-open session with `/mcp`, then select `visa-cli` and `reconnect`.

## Try It

Ask your agent for something that uses a paid tool:

```text
Generate an image of a mountain lake at sunrise.
```

Visa CLI shows an approval prompt with the merchant and amount before any charge. Approve to continue, or cancel and no charge occurs.

Other examples:

```text
Make a lofi jazz track for studying.
```

```text
What is the price of Ethereum?
```

```text
Generate five logo variations and show me the best two.
```

## Costs And Limits

Common paid tools cost pennies per call. The server enforces spending limits even if your local machine is compromised.

| Item | Typical cost |
| --- | --- |
| Fast LLM call | $0.01 |
| Image generation | $0.01 to $0.08 |
| Video generation | $0.10 to $0.20 |
| Music generation | $0.02 |
| Transcription | $0.02 |
| Image upscale | $0.03 |

Default limits:

| Limit | Default |
| --- | --- |
| Per transaction | $10 |
| Per day | $10 |

Change limits from your agent with `update_spending_controls`, or inspect your current setup with `config_list`.

## Useful Commands

```bash
visa-cli setup
visa-cli status
visa-cli install claude
visa-cli config hud enable
```

The HUD is optional and free. It shows account and payment status in Claude Code's statusLine.

## Apps And Headless Agents

Approved users can create scoped Visa Keys for backend services and unattended agents:

```bash
visa-cli keys create my-demo-app --tools or-gpt-4o-mini --daily-cap 5 --total-cap 200
visa-cli keys list
visa-cli keys revoke 1
```

See [Visa Key API](/docs/visa-key-api) for direct HTTP execution, idempotency, pagination, error codes, and key-management details.

## Safety Basics

- Do not paste card numbers into chat. Card entry only happens in the secure browser flow.
- Paid tools require explicit approval before money moves.
- If you cancel an authorization prompt, no charge occurs.
- Your agent receives a payment tool, not your raw card number.
- Spending limits are enforced by the server.

## Troubleshooting

If setup cannot find `node` or `npm`, install Node.js 18+ and reopen your terminal.

If a payment prompt does not appear on macOS, make sure local authentication is available, then retry. On Windows and Linux, payment confirmation uses restricted server-verified controls instead of biometric prompts.

If your AI client does not show the Visa CLI tools, restart the client or reconnect the MCP server. In Claude Code, run `/mcp`, select `visa-cli`, then reconnect.