Stripe Link CLI Skill for Hermes Agent: Agent Payments via Virtual Cards & SPT

The Stripe Link CLI skill lets Hermes Agent complete purchases on your 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 or web app, Hermes cannot self-approve. This is for anyone who wants their agent to handle checkout flows or paid API calls without exposing a real card number to the agent's context.

What it does

This skill wraps the official @stripe/link-cli so Hermes can:

• Create one-time-use virtual cards for standard web checkout forms or Stripe Elements.
• Generate Shared Payment Tokens (SPT) for merchants that return an HTTP 402 response with a Stripe challenge.
• Walk through Link account setup and payment method addition on first use.
• Retrieve card details to a file (never to stdout) so the PAN stays out of agent logs.
• Clean up the card file after the purchase is done.

It is designed for scenarios where you want to delegate payment to an agent but keep approval authority in your own hands via the Link app.

Before you start

• Node.js 20+ must be on PATH. Verify with node --version.
• US-based only. A Link account requires a US phone number and address. Outside the US, auth login will fail.
• Platforms: Linux and macOS only. Windows is not supported by the upstream CLI.
• Link account: Created at https://app.link.com during first auth. The CLI walks you through it.
• Payment method: Added at https://app.link.com/wallet during first run.
• Link app: You need the Link mobile or web app to approve spend requests when they are made.
• No environment variables required. Auth state is stored locally by the CLI under its own config directory.

Install

Install globally once:

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 --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.

When not to use it

If the merchant returns an HTTP 402 without method="stripe" in the www-authenticate header, this skill cannot help. Also, 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.

Limits and gotchas

• US-only due to Link account requirements.
• Windows is not supported.
• The CLI blocks on --request-approval until the user approves or denies in the Link app. If the user is unavailable, the command times out.
• Card PAN must never enter agent context. Always use --output-file.
• Output format defaults to toon in non-TTY mode. Use --format json when parsing is needed.
• Picking the wrong credential type (card vs SPT) can fail silently or leak more data than needed.

Related skills

• mpp-agent, for handling paid API calls with Shared Payment Tokens.
• stripe-projects, for broader Stripe integration workflows.