Stripe Link CLI

Stripe Link CLI Skill

Wraps @stripe/link-cli so Hermes can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Hermes cannot self-approve.

US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated [linux, macos].

When to Use

Trigger phrases:

• "buy X", "pay for X", "make a purchase", "complete checkout"
• "get me a card", "I need a payment method"
• "log in to Link", "connect my Link wallet"
• HTTP 402 response from a merchant API with www-authenticate: ... method="stripe"

If the user wants a paid API call (HTTP 402, no checkout form), the card path is wrong — use SPT via this same skill, or hand off to the mpp-agent skill.

Prerequisites

• Node.js 20+ available on PATH (node --version)
• US-based (Link account requirement)

The Link account, payment method, and spend-approval app do NOT need to be set up before Hermes attempts to pay — the CLI walks the user through them on first run:

• A Link account at https://app.link.com — created/linked during first link-cli auth
• At least one payment method — added during first run at https://app.link.com/wallet
• The Link mobile/web app — opened to approve the first spend request when it's made

No env vars required — auth state is stored locally by the CLI under its own config directory.

Install

Install once, globally:

npm install -g @stripe/link-cli

Or invoke ad-hoc via npx @stripe/link-cli. The skill below uses the installed link-cli form.

How to Run

All commands run through the terminal tool. The CLI auto-detects non-TTY callers and emits compact toon output by default — fine for the model. Pass --format json if a step needs structured fields.

Discover commands: link-cli --llms-full. Get a command's schema before invoking: link-cli <command> --schema.

Procedure

1. Check / establish auth

link-cli auth status

If not authenticated, log in with a clear client name (this label shows in the user's Link app):

link-cli auth login --client-name "Hermes" --interval 5 --timeout 300

The --interval/--timeout form polls inline so the agent doesn't need to manage a _next step. Print the verification URL + phrase to the user and wait for the CLI to return.

Background-polling pattern (when not using inline flags): If you run auth login without --interval/--timeout (or with pty=true), it returns immediately with a verification_url, phrase, and a _next.command like auth status --interval 5 --max-attempts 60. Start that poll as a background terminal process with notify_on_complete=true so you get notified when the user approves:

link-cli auth status --interval 5 --max-attempts 60
# → run with: background=true, notify_on_complete=true, timeout=330

Print the verification URL and phrase to the user immediately — don't wait for them to ask. The background poll will notify you when auth succeeds.

Do not proceed past this step until auth status confirms login.

2. Evaluate the merchant before creating a spend request

Decide the credential type:

For 402 responses, do NOT decode the challenge manually. Pass the raw header:

link-cli mpp decode --challenge '<full WWW-Authenticate header>'

This validates the challenge and extracts the network ID + decoded request body.

3. List payment methods + shipping

link-cli payment-methods list
link-cli shipping-address list

Use the first entry unless the user specifies otherwise. The id from payment-methods list is the --payment-method-id in the next step.

4. Create the spend request

Confirm the final total with the user before issuing this command. Amounts are in cents.

link-cli spend-request create \
  --payment-method-id <pm_id> \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --context "<what is being purchased and why — MUST be ≥100 characters or the CLI returns VALIDATION_ERROR too_small>" \
  --amount <cents> \
  --line-item "name:<item>,unit_amount:<cents>,quantity:1" \
  --total "type:total,display_text:Total,amount:<cents>" \
  --request-approval

For MPP merchants add --credential-type shared_payment_token.

--request-approval sends the approval push notification to the user's Link app and returns immediately with status: "pending_approval". It does NOT poll — the response includes a _next.command (spend-request retrieve <id> --interval 2 --max-attempts 300) that you must run separately to poll for approval.

Best pattern: After create --request-approval returns, immediately start a background retrieve call that combines polling + card retrieval in one shot (see Section 5). This eliminates the gap between approval and retrieval that causes card expiry.

5. Retrieve the credential — SECURELY

Do not print card details to stdout. Use --output-file so the PAN never enters the agent's transcript or logs.

All five options are required by the schema even though they appear to have defaults — omitting any of --timeout, --interval, --max-attempts, --force, or --include can cause a terminated error. Always pass all five explicitly:

Combined poll + retrieve (preferred): Combines approval polling and card retrieval in one background call. Run this immediately after create --request-approval returns — it polls until the user approves, then retrieves the card in the same process, eliminating the approval-to-retrieval gap:

link-cli spend-request retrieve <lsrq_id> \
  --include card \
  --output-file /tmp/link-card.json \
  --timeout 600 \
  --interval 2 \
  --max-attempts 0 \
  --force \
  --format json
# → run with: background=true, notify_on_complete=true, timeout=660

Post-approval retrieve (only when poll already confirmed approval): If you already polled separately (e.g. via a background process) and confirmed status: "approved", retrieve the card with zero interval:

link-cli spend-request retrieve <lsrq_id> \
  --include card \
  --output-file /tmp/link-card.json \
  --timeout 30 \
  --interval 0 \
  --max-attempts 0 \
  --force \
  --format json

The file is written with 0600 perms; stdout shows only redacted fields (brand, last4, expiry) plus a card_output_file path.