stripe-link-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stripe Link CLI

Skill by ara.so — Devtools Skills collection.

Link CLI lets AI agents get secure, one-time-use payment credentials from a Link wallet to complete purchases on your behalf. Your real card details are never exposed — you approve every purchase through the Link mobile app. The CLI can produce virtual cards (PAN) for standard web checkouts or Shared Payment Tokens (SPT) for Machine Payment Protocol (MPP) merchants.

由ara.so开发的Skill——Devtools Skills集合。

Link CLI允许AI Agent从Link钱包获取安全的一次性支付凭证，代表你完成购物。你的真实银行卡信息永远不会暴露——你需要通过Link移动应用批准每一笔交易。CLI可以生成用于标准网页结账的虚拟卡（PAN），或用于Machine Payment Protocol（MPP）商户的Shared Payment Tokens（SPT）。

Installation

安装

bash

npm i -g @stripe/link-cli

Or run directly with

npx

bash

npx @stripe/link-cli

bash

npm i -g @stripe/link-cli

或者直接用

npx

运行：

bash

npx @stripe/link-cli

Agent Integration

Agent集成

Install as a skill:

bash

npx skills add stripe/link-cli

By default, commands use

toon

output (compact, LLM-friendly text) when called from agents (non-TTY). All commands accept

--format [json|yaml|md|jsonl]

for structured output.

作为Skill安装：

bash

npx skills add stripe/link-cli

默认情况下，当由Agent（非TTY环境）调用时，命令会使用

toon

格式输出（简洁、适合LLM的文本）。所有命令都支持通过

--format [json|yaml|md|jsonl]

参数指定结构化输出格式。

MCP Server

MCP服务器

Add to your MCP client config (

.mcp.json

json

{
  "mcpServers": {
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}

添加到你的MCP客户端配置文件（

.mcp.json

）：

json

{
  "mcpServers": {
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}

Authentication

身份验证

Before using Link CLI, authenticate with a Link account:

bash

undefined

使用Link CLI前，需通过Link账户进行身份验证：

bash

undefined

Login with custom client name for identification

使用自定义客户端名称登录以便识别

link-cli auth login --client-name "Claude Code"

Check authentication status

检查身份验证状态

link-cli auth status

Logout

登出

link-cli auth logout


The login flow provides a verification URL and short phrase. The user visits the URL, logs in to Link, and enters the phrase to approve the connection.

**Using custom auth file:**

```bash

link-cli auth logout


登录流程会提供一个验证URL和短句。用户访问该URL，登录Link账户，输入短句即可批准连接。

**使用自定义身份验证文件：**

```bash

Store credentials in specific file

将凭证存储到指定文件

link-cli auth login --auth /path/to/auth.json

Use credentials from specific file (all commands)

使用指定文件中的凭证（所有命令通用）

link-cli payment-methods list --auth /path/to/auth.json


Or set `LINK_AUTH_FILE` environment variable:

```bash
export LINK_AUTH_FILE=/path/to/auth.json
link-cli payment-methods list

link-cli payment-methods list --auth /path/to/auth.json


或者设置`LINK_AUTH_FILE`环境变量：

```bash
export LINK_AUTH_FILE=/path/to/auth.json
link-cli payment-methods list

Payment Methods & Addresses

支付方式与地址

List Payment Methods

列出支付方式

bash

undefined

bash

undefined

List all saved payment methods

列出所有已保存的支付方式

link-cli payment-methods list

JSON output

JSON格式输出

link-cli payment-methods list --format json


Returns cards and bank accounts saved to the Link account. Use the `id` field as `payment_method_id` when creating spend requests.

link-cli payment-methods list --format json


返回已保存到Link账户的银行卡和银行账户信息。创建消费请求时，使用`id`字段作为`payment_method_id`参数。

List Shipping Addresses

列出收货地址

bash

undefined

bash

undefined

List saved shipping addresses

列出已保存的收货地址

link-cli shipping-address list

JSON output

JSON格式输出

link-cli shipping-address list --format json

undefined

link-cli shipping-address list --format json

undefined

Spend Requests

消费请求

A spend request is a request for payment credentials tied to a specific purchase. The lifecycle: create → request approval → approved (with credentials).

消费请求是与特定购物行为绑定的支付凭证请求。生命周期为：创建 → 请求批准 → 已批准（获取凭证）。

Create Spend Request

创建消费请求

bash

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --merchant-name "Stripe Press" \
  --merchant-url "https://press.stripe.com" \
  --context "Purchasing 'Working in Public' from press.stripe.com. The user initiated this purchase through the shopping assistant to learn about open source sustainability." \
  --amount 3500 \
  --line-item "name:Working in Public,unit_amount:3500,quantity:1" \
  --total "type:total,display_text:Total,amount:3500" \
  --request-approval

Required fields:

```
--payment-method-id
```
: ID from
```
payment-methods list
```
```
--merchant-name
```
: Merchant display name
```
--merchant-url
```
: Merchant website URL
```
--context
```
: Detailed description (minimum 100 characters)
```
--amount
```
: Total amount in cents (max 50000)

Optional fields:

```
--currency
```
: 3-letter ISO code (default:
```
usd
```
)

--credential-type

virtual_card

(default) or

shared_payment_token

--shipping-address-id

: ID from

shipping-address list

```
--request-approval
```
: Request approval immediately after creation

Constraints:

```
context
```
must be at least 100 characters
```
amount
```
must not exceed 50000 cents
```
currency
```
must be valid 3-letter ISO code

bash

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --merchant-name "Stripe Press" \
  --merchant-url "https://press.stripe.com" \
  --context "Purchasing 'Working in Public' from press.stripe.com. The user initiated this purchase through the shopping assistant to learn about open source sustainability." \
  --amount 3500 \
  --line-item "name:Working in Public,unit_amount:3500,quantity:1" \
  --total "type:total,display_text:Total,amount:3500" \
  --request-approval

必填字段：

```
--payment-method-id
```
：来自
```
payment-methods list
```
的ID
```
--merchant-name
```
：商户显示名称
```
--merchant-url
```
：商户网站URL
```
--context
```
：详细描述（至少100个字符）
```
--amount
```
：总金额（单位：分，最高50000分）

可选字段：

```
--currency
```
：3位ISO货币代码（默认：
```
usd
```
）

--credential-type

：

virtual_card

（默认）或

shared_payment_token

--shipping-address-id

：来自

shipping-address list

的ID

```
--request-approval
```
：创建后立即请求批准

限制条件：

```
context
```
必须至少100个字符
```
amount
```
不得超过50000分
```
currency
```
必须是有效的3位ISO代码

Line Items Format

商品项格式

Use repeatable

--line-item

flags with

key:value

pairs:

bash

--line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners,sku:SKU-123" \
--line-item "name:Socks,unit_amount:1500,quantity:2"

Available keys:

```
name
```
(required)
```
quantity
```
```
unit_amount
```
```
description
```
```
sku
```
```
url
```
```
image_url
```
```
product_url
```

使用可重复的

--line-item

参数，采用

key:value

键值对格式：

bash

--line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners,sku:SKU-123" \
--line-item "name:Socks,unit_amount:1500,quantity:2"

可用键：

```
name
```
（必填）
```
quantity
```
```
unit_amount
```
```
description
```
```
sku
```
```
url
```
```
image_url
```
```
product_url
```

Totals Format

总计项格式

Use repeatable

--total

flags:

bash

--total "type:subtotal,display_text:Subtotal,amount:12000" \
--total "type:shipping,display_text:Shipping,amount:500" \
--total "type:tax,display_text:Tax,amount:950" \
--total "type:total,display_text:Total,amount:13450"

Required keys:

type

: One of

subtotal

tax

total

items_base_amount

items_discount

discount

fulfillment

shipping

fee

gift_wrap

tip

store_credit

```
display_text
```
```
amount
```

使用可重复的

--total

参数：

bash

--total "type:subtotal,display_text:Subtotal,amount:12000" \
--total "type:shipping,display_text:Shipping,amount:500" \
--total "type:tax,display_text:Tax,amount:950" \
--total "type:total,display_text:Total,amount:13450"

必填键：

type

：可选值包括

subtotal

tax

total

items_base_amount

items_discount

discount

fulfillment

shipping

fee

gift_wrap

tip

store_credit

```
display_text
```
```
amount
```

Test Mode

测试模式

Create test credentials without real payment methods:

bash

link-cli spend-request create \
  --test \
  --payment-method-id pm_test_card \
  --merchant-name "Test Merchant" \
  --merchant-url "https://example.com" \
  --context "Testing payment flow with test credentials. This is a development test to verify the integration before using real payment methods." \
  --amount 1000 \
  --line-item "name:Test Item,unit_amount:1000,quantity:1" \
  --total "type:total,display_text:Total,amount:1000"

无需真实支付方式即可创建测试凭证：

bash

link-cli spend-request create \
  --test \
  --payment-method-id pm_test_card \
  --merchant-name "Test Merchant" \
  --merchant-url "https://example.com" \
  --context "Testing payment flow with test credentials. This is a development test to verify the integration before using real payment methods." \
  --amount 1000 \
  --line-item "name:Test Item,unit_amount:1000,quantity:1" \
  --total "type:total,display_text:Total,amount:1000"

Retrieve Spend Request

获取消费请求

bash

undefined

bash

undefined

Basic retrieval (card masked)

基础获取（银行卡信息脱敏）

link-cli spend-request retrieve lsrq_001

Include unmasked card details

包含未脱敏的银行卡详情

link-cli spend-request retrieve lsrq_001 --include card

Write card to secure file (stdout shows redacted data only)

将银行卡信息写入安全文件（标准输出仅显示脱敏数据）

link-cli spend-request retrieve lsrq_001
--include card
--output-file /tmp/link-card.json
--format json


When using `--output-file`:
- File is created with `0600` permissions
- Command fails if file exists unless `--force` is passed
- Stdout shows redacted card data (brand, last4, expiry)
- Full card details written to file
- JSON output includes `card_output_file` path instead of full `card` object

link-cli spend-request retrieve lsrq_001
--include card
--output-file /tmp/link-card.json
--format json


使用`--output-file`参数时：
- 文件会以`0600`权限创建
- 若文件已存在，命令会执行失败，除非添加`--force`参数
- 标准输出显示脱敏的银行卡数据（品牌、后四位、有效期）
- 完整银行卡详情会写入文件
- JSON输出中会包含`card_output_file`路径，而非完整的`card`对象

Polling for Approval

轮询批准状态

typescript

// Poll until terminal status (approved, denied, expired, canceled)
link-cli spend-request retrieve lsrq_001 \
  --interval 2 \
  --max-attempts 300

Polling exits successfully only when the request reaches a terminal status. If polling times out or exhausts attempts while the request is still pending, the command exits with non-zero status and

code: "POLLING_TIMEOUT"

typescript

// 轮询直到进入终端状态（已批准、已拒绝、已过期、已取消）
link-cli spend-request retrieve lsrq_001 \
  --interval 2 \
  --max-attempts 300

只有当请求进入终端状态时，轮询才会成功退出。如果请求仍处于待处理状态时轮询超时或达到最大尝试次数，命令会以非零状态退出，并返回

code: "POLLING_TIMEOUT"

。

Update Spend Request

更新消费请求

bash

undefined

bash

undefined

Update before approval

在批准前更新请求

link-cli spend-request update lsrq_001
--merchant-url https://press.stripe.com/working-in-public
--amount 4000

undefined

link-cli spend-request update lsrq_001
--merchant-url https://press.stripe.com/working-in-public
--amount 4000

undefined

Request Approval

请求批准

bash

undefined

bash

undefined

Request approval separately (alternative to --request-approval flag)

单独请求批准（替代--request-approval参数）

link-cli spend-request request-approval lsrq_001

undefined

link-cli spend-request request-approval lsrq_001

undefined

Cancel Spend Request

取消消费请求

bash

undefined

bash

undefined

Cancel from any non-terminal state

在任何非终端状态下取消请求

link-cli spend-request cancel lsrq_001

undefined

link-cli spend-request cancel lsrq_001

undefined

Using Credentials

使用凭证

Virtual Card Checkout

虚拟卡结账

After approval, retrieve the spend request with card details:

bash

link-cli spend-request retrieve lsrq_001 --include card --output-file /tmp/card.json --format json

The card object includes:

```
number
```
: Full card number
```
cvc
```
: CVV/CVC code
```
exp_month
```
: Expiration month
```
exp_year
```
: Expiration year
```
billing_address
```
: Address object
```
valid_until
```
: Timestamp when credentials expire

Enter these details into the merchant's checkout form.

TypeScript example:

typescript

import { readFileSync } from 'fs';

// Read card from secure file
const cardData = JSON.parse(readFileSync('/tmp/card.json', 'utf8'));
const card = cardData.card;

// Use card details in checkout automation
await fillCheckoutForm({
  cardNumber: card.number,
  cvc: card.cvc,
  expMonth: card.exp_month,
  expYear: card.exp_year,
  billingAddress: card.billing_address
});

批准后，获取包含银行卡详情的消费请求：

bash

link-cli spend-request retrieve lsrq_001 --include card --output-file /tmp/card.json --format json

银行卡对象包含：

```
number
```
：完整银行卡号
```
cvc
```
：CVV/CVC码
```
exp_month
```
：到期月份
```
exp_year
```
：到期年份
```
billing_address
```
：地址对象
```
valid_until
```
：凭证过期时间戳

将这些信息输入商户的结账表单即可完成支付。

TypeScript示例：

typescript

import { readFileSync } from 'fs';

// 从安全文件读取银行卡信息
const cardData = JSON.parse(readFileSync('/tmp/card.json', 'utf8'));
const card = cardData.card;

// 在结账自动化中使用银行卡详情
await fillCheckoutForm({
  cardNumber: card.number,
  cvc: card.cvc,
  expMonth: card.exp_month,
  expYear: card.exp_year,
  billingAddress: card.billing_address
});

Machine Payment Protocol (MPP)

For merchants supporting MPP, create a spend request with

credential_type: shared_payment_token

bash

undefined

对于支持MPP的商户，创建消费请求时指定

credential_type: shared_payment_token

：

bash

undefined

Create SPT spend request

创建SPT消费请求

link-cli spend-request create
--payment-method-id csmrpd_xxx
--merchant-name "Climate Stripe"
--merchant-url "https://climate.stripe.dev"
--context "Contributing to climate initiatives through climate.stripe.dev. The user wants to offset carbon emissions from their recent travel."
--amount 100
--credential-type "shared_payment_token"
--line-item "name:Carbon Offset,unit_amount:100,quantity:1"
--total "type:total,display_text:Total,amount:100"
--request-approval

After approval, pay using MPP

批准后，使用MPP完成支付

link-cli mpp pay https://climate.stripe.dev/api/contribute
--spend-request-id lsrq_001
--method POST
--data '{"amount":100}'
--header "Content-Type: application/json"


The SPT is one-time-use. If payment fails, create a new spend request.

link-cli mpp pay https://climate.stripe.dev/api/contribute
--spend-request-id lsrq_001
--method POST
--data '{"amount":100}'
--header "Content-Type: application/json"


SPT为一次性使用。若支付失败，需创建新的消费请求。

Decode MPP Challenge

解码MPP挑战

Extract payment information from a

WWW-Authenticate

header:

bash

link-cli mpp decode \
  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'

Returns the

network_id

needed for SPT spend requests and decoded challenge parameters.

从

WWW-Authenticate

头中提取支付信息：

bash

link-cli mpp decode \
  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'

返回创建SPT消费请求所需的

network_id

以及解码后的挑战参数。

Command Schema

命令Schema

Get full JSON schema for any command:

bash

undefined

获取任意命令的完整JSON Schema：

bash

undefined

Get schema for create command

获取create命令的Schema

link-cli spend-request create --schema

List all commands in LLM-friendly format

以适合LLM的格式列出所有命令

link-cli --llms-full

undefined

link-cli --llms-full

undefined

Common Patterns

常见模式

Agent Purchase Flow (Virtual Card)

Agent购物流程（虚拟卡）

typescript

import { execSync } from 'child_process';

// 1. Get payment methods
const pmResult = execSync('link-cli payment-methods list --format json', { encoding: 'utf8' });
const paymentMethods = JSON.parse(pmResult);
const pmId = paymentMethods[0].id;

// 2. Create spend request
const createCmd = `link-cli spend-request create \
  --payment-method-id ${pmId} \
  --merchant-name "Acme Store" \
  --merchant-url "https://acme.example" \
  --context "Purchasing office supplies from acme.example. The user requested pens and notebooks for the team meeting next week." \
  --amount 2500 \
  --line-item "name:Blue Pens,unit_amount:1000,quantity:1" \
  --line-item "name:Notebook,unit_amount:1500,quantity:1" \
  --total "type:total,display_text:Total,amount:2500" \
  --request-approval \
  --format json`;

const createResult = JSON.parse(execSync(createCmd, { encoding: 'utf8' }));
const spendRequestId = createResult.id;

// 3. Poll for approval
const pollCmd = `link-cli spend-request retrieve ${spendRequestId} \
  --interval 2 \
  --max-attempts 300 \
  --include card \
  --output-file /tmp/card-${spendRequestId}.json \
  --format json`;

const approvedResult = JSON.parse(execSync(pollCmd, { encoding: 'utf8' }));

// 4. Read card from secure file
const cardFile = `/tmp/card-${spendRequestId}.json`;
const cardData = JSON.parse(readFileSync(cardFile, 'utf8'));

// 5. Use card in checkout
await completeCheckout(cardData.card);

typescript

import { execSync } from 'child_process';

// 1. 获取支付方式
const pmResult = execSync('link-cli payment-methods list --format json', { encoding: 'utf8' });
const paymentMethods = JSON.parse(pmResult);
const pmId = paymentMethods[0].id;

// 2. 创建消费请求
const createCmd = `link-cli spend-request create \
  --payment-method-id ${pmId} \
  --merchant-name "Acme Store" \
  --merchant-url "https://acme.example" \
  --context "Purchasing office supplies from acme.example. The user requested pens and notebooks for the team meeting next week." \
  --amount 2500 \
  --line-item "name:Blue Pens,unit_amount:1000,quantity:1" \
  --line-item "name:Notebook,unit_amount:1500,quantity:1" \
  --total "type:total,display_text:Total,amount:2500" \
  --request-approval \
  --format json`;

const createResult = JSON.parse(execSync(createCmd, { encoding: 'utf8' }));
const spendRequestId = createResult.id;

// 3. 轮询批准状态
const pollCmd = `link-cli spend-request retrieve ${spendRequestId} \
  --interval 2 \
  --max-attempts 300 \
  --include card \
  --output-file /tmp/card-${spendRequestId}.json \
  --format json`;

const approvedResult = JSON.parse(execSync(pollCmd, { encoding: 'utf8' }));

// 4. 从安全文件读取银行卡信息
const cardFile = `/tmp/card-${spendRequestId}.json`;
const cardData = JSON.parse(readFileSync(cardFile, 'utf8'));

// 5. 使用银行卡完成结账
await completeCheckout(cardData.card);

Agent Purchase Flow (MPP)

Agent购物流程（MPP）

typescript

import { execSync } from 'child_process';

// 1. Decode MPP challenge to get network_id
const challenge = response.headers['www-authenticate'];
const decodeResult = execSync(
  `link-cli mpp decode --challenge '${challenge}' --format json`,
  { encoding: 'utf8' }
);
const { network_id } = JSON.parse(decodeResult);

// 2. Create SPT spend request
const createCmd = `link-cli spend-request create \
  --payment-method-id ${pmId} \
  --merchant-name "Climate Stripe" \
  --merchant-url "https://climate.stripe.dev" \
  --context "Contributing to climate offset program through climate.stripe.dev. The user wants to neutralize carbon emissions from their last flight." \
  --amount 100 \
  --credential-type "shared_payment_token" \
  --line-item "name:Carbon Offset,unit_amount:100,quantity:1" \
  --total "type:total,display_text:Total,amount:100" \
  --request-approval \
  --format json`;

const createResult = JSON.parse(execSync(createCmd, { encoding: 'utf8' }));
const spendRequestId = createResult.id;

// 3. Poll for approval
execSync(`link-cli spend-request retrieve ${spendRequestId} --interval 2 --max-attempts 300`);

// 4. Pay using MPP
const payCmd = `link-cli mpp pay https://climate.stripe.dev/api/contribute \
  --spend-request-id ${spendRequestId} \
  --method POST \
  --data '{"amount":100}' \
  --header "Content-Type: application/json" \
  --format json`;

const payResult = JSON.parse(execSync(payCmd, { encoding: 'utf8' }));

typescript

import { execSync } from 'child_process';

// 1. 解码MPP挑战获取network_id
const challenge = response.headers['www-authenticate'];
const decodeResult = execSync(
  `link-cli mpp decode --challenge '${challenge}' --format json`,
  { encoding: 'utf8' }
);
const { network_id } = JSON.parse(decodeResult);

// 2. 创建SPT消费请求
const createCmd = `link-cli spend-request create \
  --payment-method-id ${pmId} \
  --merchant-name "Climate Stripe" \
  --merchant-url "https://climate.stripe.dev" \
  --context "Contributing to climate offset program through climate.stripe.dev. The user wants to neutralize carbon emissions from their last flight." \
  --amount 100 \
  --credential-type "shared_payment_token" \
  --line-item "name:Carbon Offset,unit_amount:100,quantity:1" \
  --total "type:total,display_text:Total,amount:100" \
  --request-approval \
  --format json`;

const createResult = JSON.parse(execSync(createCmd, { encoding: 'utf8' }));
const spendRequestId = createResult.id;

// 3. 轮询批准状态
execSync(`link-cli spend-request retrieve ${spendRequestId} --interval 2 --max-attempts 300`);

// 4. 使用MPP完成支付
const payCmd = `link-cli mpp pay https://climate.stripe.dev/api/contribute \
  --spend-request-id ${spendRequestId} \
  --method POST \
  --data '{"amount":100}' \
  --header "Content-Type: application/json" \
  --format json`;

const payResult = JSON.parse(execSync(payCmd, { encoding: 'utf8' }));

Multiple Auth Sessions

多身份验证会话

typescript

// User 1 session
process.env.LINK_AUTH_FILE = '/secure/user1-auth.json';
execSync('link-cli auth login --client-name "User1 Agent"');

// User 2 session
process.env.LINK_AUTH_FILE = '/secure/user2-auth.json';
execSync('link-cli auth login --client-name "User2 Agent"');

// Use different sessions
function getPaymentMethodsForUser(userId: string) {
  const authFile = `/secure/${userId}-auth.json`;
  return execSync(`link-cli payment-methods list --auth ${authFile} --format json`, {
    encoding: 'utf8'
  });
}

typescript

// 用户1会话
process.env.LINK_AUTH_FILE = '/secure/user1-auth.json';
execSync('link-cli auth login --client-name "User1 Agent"');

// 用户2会话
process.env.LINK_AUTH_FILE = '/secure/user2-auth.json';
execSync('link-cli auth login --client-name "User2 Agent"');

// 使用不同会话
function getPaymentMethodsForUser(userId: string) {
  const authFile = `/secure/${userId}-auth.json`;
  return execSync(`link-cli payment-methods list --auth ${authFile} --format json`, {
    encoding: 'utf8'
  });
}

Environment Variables

环境变量

Variable	Description
`LINK_AUTH_FILE`	Override auth credential file path (flag `--auth` takes precedence)
`LINK_API_BASE_URL`	Override API base URL
`LINK_AUTH_BASE_URL`	Override auth base URL
`LINK_HTTP_PROXY`	Route requests through HTTP proxy (requires `undici` )
`NO_UPDATE_NOTIFIER`	Set to `1` to suppress update checks (useful in CI)

变量	描述
`LINK_AUTH_FILE`	覆盖身份验证凭证文件路径（ `--auth` 参数优先级更高）
`LINK_API_BASE_URL`	覆盖API基础URL
`LINK_AUTH_BASE_URL`	覆盖身份验证基础URL
`LINK_HTTP_PROXY`	通过HTTP代理路由请求（需要 `undici` 依赖）
`NO_UPDATE_NOTIFIER`	设置为 `1` 以禁用更新检查（适用于CI环境）

Troubleshooting

故障排除

Authentication Issues

身份验证问题

Problem:

link-cli auth status

shows

authenticated: false

Solution:

bash

undefined

问题：

link-cli auth status

显示

authenticated: false

解决方案：

bash

undefined

Logout and login again

登出后重新登录

link-cli auth logout link-cli auth login --client-name "My Agent"

undefined

link-cli auth logout link-cli auth login --client-name "My Agent"

undefined

Spend Request Denied

消费请求被拒绝

Problem: User denies spend request in Link app

Solution: The polling command exits with status reflecting denial. Create a new spend request with updated context or amounts:

bash

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --merchant-name "Updated Merchant" \
  --merchant-url "https://merchant.example" \
  --context "Revised purchase with updated details per user feedback. The user now wants the blue model instead of red, which has a different price point." \
  --amount 4000 \
  --line-item "name:Blue Model,unit_amount:4000,quantity:1" \
  --total "type:total,display_text:Total,amount:4000" \
  --request-approval

问题： 用户在Link应用中拒绝了消费请求

解决方案： 轮询命令会返回代表拒绝的状态码。创建新的消费请求并更新上下文或金额：

bash

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --merchant-name "Updated Merchant" \
  --merchant-url "https://merchant.example" \
  --context "Revised purchase with updated details per user feedback. The user now wants the blue model instead of red, which has a different price point." \
  --amount 4000 \
  --line-item "name:Blue Model,unit_amount:4000,quantity:1" \
  --total "type:total,display_text:Total,amount:4000" \
  --request-approval

Context Too Short

上下文过短

Problem:

context must be at least 100 characters

Solution: Provide detailed purchase context:

bash

--context "Purchasing premium subscription to ExampleService for the team. This will give us access to advanced features including API access, priority support, and increased usage limits that we need for the upcoming project launch."

问题： 提示

context must be at least 100 characters

解决方案： 提供详细的购物上下文：

bash

--context "Purchasing premium subscription to ExampleService for the team. This will give us access to advanced features including API access, priority support, and increased usage limits that we need for the upcoming project launch."

Amount Exceeds Limit

金额超出限制

Problem:

amount must not exceed 50000

Solution: Link CLI enforces a 50000 cent ($500) limit per request. For larger purchases, split into multiple spend requests or handle outside Link CLI.

问题： 提示

amount must not exceed 50000

解决方案： Link CLI限制每笔请求最高50000分（500美元）。对于大额购物，可拆分为多个消费请求或通过其他方式处理。

Polling Timeout

轮询超时

Problem: Polling exits with

code: "POLLING_TIMEOUT"

Solution: Increase

--max-attempts

or check if user has Link app installed:

bash

undefined

问题： 轮询退出并返回

code: "POLLING_TIMEOUT"

解决方案： 增加

--max-attempts

参数值，或检查用户是否安装了Link应用：

bash

undefined

Poll for up to 15 minutes (2s interval × 450 attempts)

轮询最长15分钟（2秒间隔 × 450次尝试）

link-cli spend-request retrieve lsrq_001
--interval 2
--max-attempts 450

undefined

link-cli spend-request retrieve lsrq_001
--interval 2
--max-attempts 450

undefined

MPP Payment Fails

MPP支付失败

Problem: SPT payment returns error

Solution: SPTs are one-time-use. Create a new spend request and try again:

bash

undefined

问题： SPT支付返回错误

解决方案： SPT为一次性使用。创建新的消费请求并重试：

bash

undefined

Cancel old request

取消旧请求

link-cli spend-request cancel lsrq_001

Create new request

创建新请求

link-cli spend-request create
--payment-method-id csmrpd_xxx
--credential-type "shared_payment_token" \

... rest of flags

undefined

link-cli spend-request create
--payment-method-id csmrpd_xxx
--credential-type "shared_payment_token" \

... 其他参数

undefined

File Already Exists

文件已存在

Problem:

--output-file

fails because file exists

Solution: Use

--force

to overwrite or choose different path:

bash

link-cli spend-request retrieve lsrq_001 \
  --include card \
  --output-file /tmp/card.json \
  --force

问题：

--output-file

参数执行失败，提示文件已存在

解决方案： 使用

--force

参数覆盖文件，或选择其他路径：

bash

link-cli spend-request retrieve lsrq_001 \
  --include card \
  --output-file /tmp/card.json \
  --force

Demo & Onboarding

演示与入门

Interactive Demo

交互式演示

bash

undefined

bash

undefined

Run interactive demo (test mode)

运行交互式演示（测试模式）

link-cli demo

Only virtual card flow

仅演示虚拟卡流程

link-cli demo --only-card

Only MPP/SPT flow

仅演示MPP/SPT流程

link-cli demo --only-spt

undefined

link-cli demo --only-spt

undefined

Guided Onboarding

引导式入门

bash

undefined

bash

undefined

Complete setup flow

完成设置流程

link-cli onboard


Walks through authentication, payment method checks, app download, and both demo flows.

link-cli onboard


引导你完成身份验证、支付方式检查、应用下载以及两种演示流程。