stripe-link-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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]

封装@stripe/link-cli，使Hermes能够代表用户使用一次性虚拟卡或共享支付令牌（SPT）完成购买。每一笔支出都需要通过Link移动端/网页应用内的批准——Hermes无法自行批准。

目前仅支持美国地区（需Link账户）。上游CLI不支持Windows系统，因此本技能仅适用于

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

触发短语：

"购买X"、"为X付款"、"完成购买"、"完成结账"
"给我一张卡"、"我需要支付方式"
"登录Link"、"连接我的Link钱包"
商户API返回HTTP 402响应，且包含
```
www-authenticate: ... method="stripe"
```
头信息

如果用户需要进行付费API调用（返回HTTP 402，但无结账表单），则不应使用

card

路径——需通过本技能使用SPT，或转交至

mpp-agent

技能处理。

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.

系统
```
PATH
```
中需存在Node.js 20+版本（可通过
```
node --version
```
验证）
位于美国地区（需Link账户）

在Hermes尝试支付前，无需预先设置Link账户、支付方式和支出批准应用——首次运行CLI时会引导用户完成这些步骤：

Link账户：访问https://app.link.com，首次`link-cli`认证时创建/关联
至少一种支付方式：首次运行时在https://app.link.com/wallet添加
Link移动端/网页应用：发起首次支出请求时需打开该应用进行批准

无需设置环境变量——CLI会在自身配置目录下本地存储认证状态。

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.

全局安装一次：

npm install -g @stripe/link-cli

或通过

npx @stripe/link-cli

临时调用。以下技能说明使用已安装的

link-cli

形式。

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

所有命令通过

terminal

工具执行。CLI会自动检测非TTY调用者，默认输出简洁的

toon

格式——适合模型处理。若某步骤需要结构化字段，可传递

--format json

参数。

查看所有命令：

link-cli --llms-full

。调用前查看命令的 schema：

link-cli <command> --schema

。

Procedure

操作流程

1. Check / establish auth

1. 检查/建立认证

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

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

link-cli auth status

若未认证，使用清晰的客户端名称登录（该名称会显示在用户的Link应用中）：

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

--interval

--timeout

参数会进行轮询，因此Agent无需管理

_next

步骤。向用户展示验证URL和短语，等待CLI返回结果。

后台轮询模式（不使用内联标志时）： 如果运行

auth login

时未添加

--interval

--timeout

参数（或使用

pty=true

），命令会立即返回

verification_url

、

phrase

以及类似

auth status --interval 5 --max-attempts 60

的

_next.command

。需启动该轮询作为后台终端进程，并设置

notify_on_complete=true

，以便用户批准时收到通知：

link-cli auth status --interval 5 --max-attempts 60

→ run with: background=true, notify_on_complete=true, timeout=330

→ 运行参数：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.**


立即向用户展示验证URL和短语——不要等待用户询问。后台轮询会在认证成功时通知你。

**在`auth status`确认登录前，请勿进行下一步操作。**

2. Evaluate the merchant before creating a spend request

2. 创建支出请求前评估商户

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.

确定凭证类型：

商户界面	`--credential-type`
标准网页结账表单 / Stripe Elements	`card` （默认）
返回HTTP 402响应，且 `www-authenticate` 头中包含 `method="stripe"`	`shared_payment_token`
返回HTTP 402响应，但 `www-authenticate` 头中无 `method="stripe"`	不支持——终止操作

对于402响应，请勿手动解码挑战信息。直接传递原始头信息：

link-cli mpp decode --challenge '<完整的WWW-Authenticate头内容>'

该命令会验证挑战信息，并提取网络ID和解码后的请求体。

3. List payment methods + shipping

3. 列出支付方式和配送地址

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.

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

除非用户指定，否则使用第一个条目。

payment-methods list

返回的

id

即为下一步的

--payment-method-id

参数值。

4. Create the spend request

4. 创建支出请求

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.

在执行此命令前，需与用户确认最终金额。金额单位为美分。

link-cli spend-request create \
  --payment-method-id <pm_id> \
  --merchant-name "<商户名称>" \
  --merchant-url "<商户网址>" \
  --context "<购买内容及原因——必须≥100字符，否则CLI会返回VALIDATION_ERROR too_small错误>" \
  --amount <金额（美分）> \
  --line-item "name:<商品名称>,unit_amount:<单价（美分）>,quantity:1" \
  --total "type:total,display_text:总计,amount:<总金额（美分）>" \
  --request-approval

对于MPP商户，需添加

--credential-type shared_payment_token

参数。

--request-approval

会向用户的Link应用发送批准推送通知，并立即返回

status: "pending_approval"

。该命令不会进行轮询——响应中包含

_next.command

（

spend-request retrieve <id> --interval 2 --max-attempts 300

），需单独执行该命令以轮询批准状态。

最佳模式： 在

create --request-approval

返回后，立即启动后台

retrieve

调用，将轮询和卡片获取合并为一步（见第5节）。这样可以消除批准与获取卡片之间的时间差，避免卡片过期。

5. Retrieve the credential — SECURELY

5. 安全获取凭证

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

请勿将卡片详情打印到标准输出。 使用

--output-file

参数，确保卡号（PAN）不会进入Agent的对话记录或日志。

模式中的五个选项均为schema必填项，即使它们看似有默认值——省略

--timeout

、

--interval

、

--max-attempts

、

--force

或

--include

中的任何一个都可能导致

terminated

错误。请始终显式传递这五个参数：

合并轮询+获取（推荐）： 将批准轮询和卡片获取合并为一个后台调用。在

create --request-approval

返回后立即执行——它会轮询直到用户批准，然后在同一进程中获取卡片，消除批准到获取的时间差：

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

→ 运行参数：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.


**批准后获取（仅当已单独轮询确认批准时）：** 如果已单独轮询（例如通过后台进程）并确认`status: "approved"`，则使用零间隔获取卡片：

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


文件会以`0600`权限写入；标准输出仅显示脱敏字段（品牌、后四位、有效期）以及`card_output_file`路径。

6. Use the credential

6. 使用凭证

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

网页结账：将文件路径交给用户，或传递给浏览器驱动工具直接从磁盘填充表单。切勿使用
```
read_file
```
或
```
cat
```
命令将卡片文件内容读入Agent的推理上下文。

MPP商户：

link-cli mpp pay <商户网址> \
  --spend-request-id <lsrq_id> \
  --method POST \
  --data '<JSON请求体>'

7. Clean up

7. 清理

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

rm -f /tmp/link-card.json

购买完成后立即删除卡片文件：

rm -f /tmp/link-card.json

Optional: run as an MCP server instead

可选：作为MCP服务器运行

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

@stripe/link-cli --mcp

通过标准输入输出以MCP工具形式暴露相同命令。如需将其注册到Hermes原生MCP：

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

然后运行

hermes mcp list

应显示

stripe-link

。同样的批准规则适用——MCP无法绕过Link应用的批准步骤。

Pitfalls

注意事项

US-only. Outside the US,
```
auth login
```
will fail. Tell the user, don't keep retrying.
--context
must be ≥100 characters. The CLI returns
```
VALIDATION_ERROR / too_small
```
if shorter. Write a detailed context string (what, why, who) — not a one-liner.
--request-approval
does NOT poll. It returns immediately with
```
pending_approval
```
and a
```
_next.command
```
. You must separately poll via
```
retrieve --interval 2 --max-attempts 300
```
(background, notify_on_complete). The previous skill text that said it "polls until they approve or deny" was wrong.
One-time cards expire ~90 seconds after approval. The window between the user approving in the Link app and you retrieving the card is very short. If the card expires, you must recreate the entire spend request and get a new approval. To avoid this: (a) use the combined poll+retrieve pattern in Section 5 so there's no gap, or (b) if you polled separately, retrieve the card immediately after seeing
```
status: "approved"
```
— do not do any other work in between.
retrieve
requires explicit options or it errors with
terminated
. Even though the schema shows defaults, omitting
```
--timeout
```
,
```
--interval
```
,
```
--max-attempts
```
,
```
--force
```
, or
```
--include
```
can fail. Always pass all five. See Section 5 for exact flags.
Token refresh failures during retrieval. If
```
retrieve
```
fails with
```
Token refresh failed (400)
```
, you need to re-auth (
```
auth login --interval 5 --timeout 300
```
) and retry. But the card may expire during re-auth — which means recreating the spend request. This is why the combined poll+retrieve pattern is strongly preferred: it retrieves the card as part of the same process that detects approval, so no token refresh gap exists.
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.
spend-request list
only shows active requests by default. Use
```
--include-history
```
to see expired/denied/terminal-state requests. Useful for debugging.

仅支持美国地区。美国以外地区运行
```
auth login
```
会失败。请告知用户，不要反复重试。
--context
必须≥100字符。如果长度不足，CLI会返回
```
VALIDATION_ERROR / too_small
```
错误。请编写详细的上下文字符串（内容、原因、对象）——不要用单行短句。
--request-approval
不会轮询。它会立即返回
```
pending_approval
```
和
```
_next.command
```
。必须通过
```
retrieve --interval 2 --max-attempts 300
```
单独进行轮询（后台运行，设置
```
notify_on_complete=true
```
）。此前技能文档中称其“会轮询直到用户批准或拒绝”的描述有误。
一次性卡片在批准后约90秒过期。用户在Link应用中批准到获取卡片的时间窗口非常短。如果卡片过期，必须重新创建整个支出请求并获取新的批准。为避免这种情况：(a) 使用第5节中的合并轮询+获取模式，消除时间差；(b) 如果已单独轮询，确认
```
status: "approved"
```
后立即获取卡片——不要在此期间进行其他操作。
retrieve
需要显式参数，否则会返回
terminated
错误。即使schema显示有默认值，省略
```
--timeout
```
、
```
--interval
```
、
```
--max-attempts
```
、
```
--force
```
或
```
--include
```
中的任何一个都可能失败。请始终传递这五个参数。具体标志见第5节。
获取过程中令牌刷新失败。如果
```
retrieve
```
返回
```
Token refresh failed (400)
```
错误，需重新认证（
```
auth login --interval 5 --timeout 300
```
）并重试。但重新认证期间卡片可能过期——这意味着需要重新创建支出请求。因此强烈推荐使用合并轮询+获取模式：它在检测到批准的同一进程中获取卡片，不存在令牌刷新的时间差。
卡片卡号（PAN）绝不能进入Agent上下文。每次都要使用
```
--output-file
```
参数。如果未使用该参数已获取卡片，仅执行
```
link-cli auth logout
```
并不足够——虽然卡片是一次性的，但仍需注意安全卫生。
--request-approval
会阻塞直到用户操作。如果用户未响应，CLI会超时。请提前告知用户预期。
多步骤
_next
命令。部分命令会返回必须执行的
```
_next.command
```
以继续操作。如有疑问，优先使用内联轮询标志（
```
--interval
```
/
```
--timeout
```
）。
非TTY模式下默认输出格式为
toon
。适合文本处理，但如果下游步骤需要解析特定字段，需传递
```
--format json
```
参数。
不要默认使用
card
类型。第2节的商户评估步骤存在的原因是，选择错误的凭证类型会导致购买失败或泄露不必要的数据。
spend-request list
默认仅显示活跃请求。使用
```
--include-history
```
参数查看已过期/已拒绝/终端状态的请求。便于调试。

Verification

验证

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

Exit code 0 means installed and logged in.

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

退出码为0表示已安装且已登录。

Reference

参考

```
references/error-fixes.md
```
— Session-verified error→fix log with exact commands: context ≥100 chars,
```
terminated
```
error, token refresh failure, card expiry, and the full correct end-to-end sequence.

```
references/error-fixes.md
```
——经过会话验证的错误→修复日志，包含确切命令：上下文≥100字符、
```
terminated
```
错误、令牌刷新失败、卡片过期以及完整正确的端到端流程。