Stripe Link CLI Skill: Agent Payments with Approvals

This optional Hermes skill wraps Stripe's Link CLI so the agent can complete purchases on a user's behalf, either with a one-time virtual card or a Shared Payment Token. Every spend requires an approval in the user's Link mobile or web app, so the agent can never approve its own transaction. Reach for it when a task ends in a checkout form, when a merchant API answers with HTTP 402, or when the user asks for a payment method.

What it does

The skill gives Hermes a structured path from "buy this" to a completed payment. It checks whether the Link CLI is authenticated, helps the agent decide which credential type a merchant needs, lists the user's saved payment methods and shipping addresses, creates a spend request, and waits for the human to approve it in the Link app. Only after approval does the agent retrieve the credential.

Two credential paths exist. A standard web checkout form or Stripe Elements page takes a card, which is a one-time-use virtual card. A merchant that returns HTTP 402 with method="stripe" in its www-authenticate header takes a shared_payment_token. The skill also covers the MPP flow for paying such merchants directly, and a cleanup step that removes the card file once the purchase is done.

Because the approval gate lives in the Link app, this is not a fully autonomous spending tool. It is an agent that prepares and executes a purchase while a human holds the final yes or no.

Before you start

• Node.js 20 or newer must be on PATH. Check with node --version.
• The user must be US-based. Link accounts are a US requirement at the moment, and the upstream CLI does not support Windows, which is why the skill is gated to linux and macos.
• No environment variables are needed. The CLI keeps auth state locally in its own config directory.

The Link account, a payment method, and the approval app do not have to exist before the agent tries to pay. The CLI walks the user through them on first run: a Link account at https://app.link.com/ is created or linked during the first link-cli auth, at least one payment method is added at https://app.link.com/wallet, and the Link mobile or web app is opened to approve the first spend request when it is made.

Install

Install once, globally:

npm install -g @stripe/link-cli

You can also invoke it ad-hoc with npx @stripe/link-cli. The rest of this guide uses the installed link-cli form.

How to run it

Every command goes through the terminal tool. The CLI detects non-TTY callers and emits compact toon output by default, which is fine for the model to read. If a later step needs structured fields, pass --format json.

To discover commands, run link-cli --llms-full. To get a command's schema before invoking it, run link-cli --schema.

Procedure

1. Check or establish auth

link-cli auth status

If the user is not authenticated, log in with a clear client name. That label appears in the user's Link app:

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

The --interval and --timeout flags make the CLI poll inline, so the agent does not have to manage a _next step. Print the verification URL and phrase to the user, then wait for the CLI to return.

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

2. Evaluate the merchant before creating a spend request

Decide which credential type the merchant needs:

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 by hand. Pass the raw header:

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

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

3. List payment methods and shipping

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

Use the first entry unless the user names a different one. The id from payment-methods list becomes 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 a deny or a 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 ~/.hermes/cache/scratch/link-card.json \
  --format json

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

6. Use the credential

For a 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 ~/.hermes/cache/scratch/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 approval rules do not change: MCP does not bypass the Link app approval step.

When not to use it

If the user wants a paid API call with no checkout form, meaning an HTTP 402 response rather than a shopping cart, the card path is the wrong tool. Use SPT through this same skill, or hand off to the mpp-agent skill. The merchant-evaluation step exists precisely because choosing the wrong credential type either fails the purchase silently or exposes more data than the task needs.

Limits and gotchas

• US-only. Outside the US, auth login fails. Tell the user and stop; do not keep retrying.
• The card PAN must never enter agent context. Use --output-file every time. If a retrieval already happened without it, running link-cli auth logout is not enough. The card is one-time-use, but rotating hygiene still matters.
• --request-approval blocks until the user acts. If the user is asleep, the CLI will hit its timeout. Set that expectation before you issue the command.
• Some commands return a multi-step _next.command that has to be executed to continue. When in doubt, prefer the inline-polling flags (--interval and --timeout).
• Output defaults to toon in non-TTY mode. That is fine for prose, but if a downstream step must parse a specific field, pass --format json.
• Do not default to card. Evaluate the merchant first.

Verification

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

Exit code 0 means the CLI is installed and logged in.

What pairs with it

The source lists two related skills. mpp-agent handles the paid-API side when a merchant answers with HTTP 402 and no checkout form is involved. stripe-projects covers the broader Stripe tooling in the same payments tier. Both are optional skills, so install them on demand the same way you installed this one.