stripe-link-cli

name	stripe-link-cli
description	Agent payments via Stripe Link — cards, SPT, approvals.
version	0.1.0
author	Teknium (teknium1), Hermes Agent
license	MIT
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["Payments","Stripe","Link","Checkout","MPP"],"related_skills":["mpp-agent","stripe-projects"]}}

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:

Merchant surface	--credential-type
Standard web checkout form / Stripe Elements	card (default)
Returns HTTP 402 with method="stripe" in www-authenticate	shared_payment_token
Returns HTTP 402 without method="stripe"	unsupported — stop

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.

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:

link-cli spend-request retrieve <lsrq_id> \
  --include card \
  --output-file /tmp/link-card.json \
  --format json

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

6. Use the credential

• For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never read_file or cat the card file into the agent's reasoning context.

• For MPP merchants:

  link-cli mpp pay <merchant-url> \
    --spend-request-id <lsrq_id> \
    --method POST \
    --data '<json body>'
  

7. Clean up

Delete the card file as soon as the purchase is done:

rm -f /tmp/link-card.json

Optional: run as an MCP server instead

@stripe/link-cli --mcp exposes the same commands as MCP tools over stdio. To register it with Hermes' native MCP:

hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"

Then hermes mcp list should show stripe-link. The same approval rules apply — MCP doesn't bypass the Link app approval step.

Pitfalls

• US-only. Outside the US, auth login will fail. Tell the user, don't keep retrying.
• Card PAN must never enter agent context. Use --output-file every time. If you've already retrieved without it, immediately link-cli auth logout is not enough — the card is one-time-use but rotate hygiene matters.
• --request-approval blocks until the user acts. If the user is asleep, the CLI will hit its timeout. Set expectations.
• Multi-step _next commands. Some commands return _next.command that must be executed to continue. When in doubt, prefer the inline-polling flags (--interval/--timeout).
• Output format defaults to toon in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass --format json.
• Don't default to card. The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed.

Verification

link-cli --version && link-cli auth status

Exit code 0 means installed and logged in.