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.

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 "<one sentence: what is being purchased and why>" \
  --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 pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout.