link-cli — Stripe Link Agent Wallet

Let AI agents get secure, one-time-use payment credentials from a Link wallet — so they can complete purchases on your behalf without ever storing your real card details. Uses the OAuth 2.0 device authorization grant (RFC 8628): no browser, no localhost callback, no API token.

Repo: https://github.com/stripe/link-cli Install: runs via npx -y @stripe/link-cli (no pre-install needed)

Auth Flow

link-cli uses device authorization. The pattern for every auth-dependent command:

1. Run the command — if unauthenticated, it returns a verification_url + phrase
2. Present the URL to the user and ask them to approve in the Link app
3. Poll until authenticated — do not wait for the user to reply before polling

Credentials are stored at ~/.config/link-cli-nodejs/config.json.

1. Log In

npx -y @stripe/link-cli auth login --format json

Returns verification_url, phrase, and _next.command. The user visits the URL and enters the phrase in their Link app.

2. Poll Until Authenticated

Use the _next.command from the login response, or:

npx -y @stripe/link-cli auth status --interval 5 --max-attempts 60 --format json

Exits when authenticated is true. The --interval / --max-attempts flags control polling behavior.

3. Check Auth Status

npx -y @stripe/link-cli auth status --format json

Returns authenticated (bool), credentials_path, and if pending, the current verification_url + phrase.

4. Log Out

npx -y @stripe/link-cli auth logout --format json

Payment Methods

5. List Payment Methods

npx -y @stripe/link-cli payment-methods list --format json

Returns saved payment methods with id, type (CARD), name, is_default, and card_details (brand, last4, exp_month, exp_year).

Spend Requests

The core flow: create a spend request → user approves in Link app → agent receives one-time credentials.

6. Create a Spend Request

npx -y @stripe/link-cli spend-request create \
  --payment-method-id "<payment-method-id>" \
  --merchant-name "Gumroad" \
  --merchant-url "https://example.com/checkout" \
  --amount 100 \
  --currency usd \
  --context "Buying HTTPZine from Gumroad — a free comic about HTTP. Patrick Collison demoed this at Stripe Sessions 2026. This is a test of the Link CLI agent payment flow." \
  --format json

Required for virtual card flow (--credential-type card, the default):

• --payment-method-id — from payment-methods list
• --merchant-name — human-readable merchant name
• --merchant-url — the merchant's website
• --amount — in cents, max 50000 ($500.00)
• --currency — 3-letter ISO code (default: usd)
• --context — min 100 characters describing the purchase and rationale

Optional:

• --credential-type shared_payment_token — for MPP/HTTP 402 flows (omits --merchant-name/--merchant-url)
• --test — use test mode (generates test card 4242 4242 4242 4242)
• --line-item name:<name>,unit_amount:<cents>,quantity:<n> — repeatable
• --total type:<type>,display_text:<text>,amount:<cents> — repeatable

Returns an approval_url and _next.command for polling.

7. Poll for Approval

npx -y @stripe/link-cli spend-request retrieve <spend-request-id> \
  --interval 2 --max-attempts 150 --format json

Exits when status is approved, denied, or expired. On timeout while pending, exits non-zero with POLLING_TIMEOUT.

8. Reveal Card Details

npx -y @stripe/link-cli spend-request retrieve <spend-request-id> \
  --include card --format json

When approved, the response includes a card object with number, cvc, brand, exp_month, exp_year, billing_address, and valid_until. The card is one-time-use and expires after valid_until.

9. Update a Spend Request

npx -y @stripe/link-cli spend-request update <spend-request-id> \
  --merchant-url "https://example.com/new-url" --format json

10. Request Approval (Separately)

If --request-approval was omitted during create:

npx -y @stripe/link-cli spend-request request-approval <spend-request-id> --format json

Machine Payments Protocol (MPP)

For merchants that support MPP/HTTP 402, skip the checkout form entirely.

11. Decode an MPP Challenge

npx -y @stripe/link-cli mpp decode \
  --challenge '<WWW-Authenticate header value>' --format json

Extracts the network_id needed for SPT spend requests.

12. Pay via MPP

npx -y @stripe/link-cli mpp pay "https://api.example.com/resource" \
  --spend-request-id "<approved-spend-request-id>" \
  --method GET --format json

The spend request must be approved and have credential_type: shared_payment_token. The token is single-use — if payment fails, create a fresh spend request.

Options: --method (GET/POST/PUT/DELETE/PATCH), --data '<json>', --header "Key: value" (repeatable).

Guided Setup

13. Interactive Onboarding

npx -y @stripe/link-cli onboard

Walks through auth, payment methods check, app download QR, and demo flows. Requires a TTY — not suitable for headless/agent-driven use.

14. Run Demo (TTY required)

npx -y @stripe/link-cli demo --only-card --format json

Test mode only. Use --only-card or --only-spt to run a single flow.

MCP Server Mode

npx -y @stripe/link-cli --mcp

Runs link-cli as a local MCP server for MCP-compatible clients.

Environment Variables

Guidelines

1. Always use --format json — the default toon format is for human TTY consumption. JSON is machine-parseable.
2. Never wait for the user between login and polling — call auth login, present the URL, and immediately start polling auth status. Same for spend requests: create, present approval_url, poll immediately.
3. Test mode for demos — use --test on spend-request create to avoid real charges during testing.
4. Context is required and must be ≥100 chars — the user reads this when approving. Describe the purchase and rationale clearly.
5. Virtual cards are one-time-use and have a short validity window (typically ~1 hour). Use them immediately after approval.
6. Credentials persist across sessions at ~/.config/link-cli-nodejs/config.json. Check auth status before assuming the user is logged in.
7. Check _next in responses — many commands return a _next.command field with the exact polling command to use.
8. Amounts are in cents — 100 = $1.00, 50000 = $500.00 (max).
9. demo and onboard require TTY — they won't work in headless sandbox environments.
10. No API token or connector needed — link-cli manages its own OAuth device flow and stores credentials locally.