link-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up Link CLI

设置Link CLI

Set up and authenticate Link CLI for the user's intended use case. After setup, use the dedicated skill for payment or financial-insight work.

根据用户的预期使用场景，设置并认证Link CLI。完成设置后，使用专用Skill处理支付或财务洞察相关工作。

1. Determine the use case

1. 确定使用场景

Infer the use case only when the user's intent is explicit:

Agent payments: buying, paying, checking out, or obtaining a payment credential.
Financial insights: reading transactions, balances, connected accounts, or spending patterns.
Both: enabling payments and financial insights.

If the intended use case is unclear, present Both first and explicitly recommend it as the default before installing, authenticating, or choosing permissions:

text

How do you plan on using Link?
1. (Recommended) Both: agent payments and financial insights
2. Agent payments only
3. Financial insights only

If the user asks for the default, accepts the recommendation, or has no preference, select Both. Otherwise, do not proceed until the user chooses or otherwise clarifies their intention.

仅当用户意图明确时，推断其使用场景：

Agent支付：购买、付款、结账或获取支付凭证。
财务洞察：查看交易记录、账户余额、关联账户或消费模式。
两者兼具：同时启用支付和财务洞察功能。

若用户的预期使用场景不明确，在安装、认证或选择权限前，先提供两者兼具选项，并明确将其作为默认推荐：

text

你计划如何使用Link？
1. （推荐）两者兼具：Agent支付和财务洞察
2. 仅Agent支付
3. 仅财务洞察

若用户询问默认选项、接受推荐或无偏好，则选择两者兼具。否则，需等待用户选择或明确意图后再继续操作。

2. Check authentication first

2. 先检查认证状态

Once the use case is known, run

auth status

as the first Link CLI command. Always do this before

auth login

auth upgrade

, or any payment or financial-data command:

bash

link-cli auth status --format json

link-cli

is unavailable, install it with

npm install -g @stripe/link-cli

, then run the status command. Alternatively, replace

link-cli

in every command with

npx @stripe/link-cli@latest

确定使用场景后，首先运行

auth status

作为Link CLI的首个命令。在执行

auth login

、

auth upgrade

或任何支付/财务数据命令前，务必先执行此操作：

bash

link-cli auth status --format json

若

link-cli

不可用，可通过

npm install -g @stripe/link-cli

安装，然后运行状态命令。或者，将所有命令中的

link-cli

替换为

npx @stripe/link-cli@latest

。

Common commands/options

常用命令/选项

List all commands:
```
link-cli --llms
```
List all commands with parameters:
```
link-cli --llms-full
```
Get a command's exact schema with
```
--schema
```
. For example,
```
link-cli auth login --schema
```
Multi-step commands return a
```
_next
```
action. For example, authenticating returns a
```
_next.command
```
that must be run to complete the flow.
By default all output is in
```
toon
```
format. Pass
```
--format [json|md|yaml]
```
to change output format.
Some commands return a verification or approval URL. These must be presented to the user clearly for their action.
```
--auth <path>
```
flag to store auth credentials in a specific file instead of the default location.
```
auth login
```
writes to this file; all other commands read from it. Example:
```
link-cli auth login --auth credentials.json --format json
```

Recommended: Run

link-cli --llms

to understand all the available commands. The

--llms-full

output is the canonical reference for parameter names, types, and valid values. Pass

--schema

before invoking a command to understand its parameters and constraints.

When present, inspect

scope

and

authorization_details

for the access required by the selected use case. Source actions appear in an authorization detail with

type: "source"

. If the response contains an

update

field, run its

update_command

, then check status again.

If there is no active session, use
```
auth login
```
.
If the active session already has the required access, do not start another authorization flow.
Do not log out merely to add access. Leave broader existing access intact unless the user explicitly asks to replace it with narrower access.

If the user is already authenticated but you need broader access (an additional

scope

--source-actions

, or

--authorization-detail

), use

auth upgrade

instead of

auth login

. It takes the same flags but, rather than stopping with an "already logged in" message, merges what you request with the current

scope

authorization_details

and starts a new approval for the superset — so existing access is never dropped. Check

auth status

first so you know what's already granted. The current session stays valid during the approval and is only replaced once the user approves the new one, so an abandoned upgrade leaves the existing session working.

The token endpoint may omit

scope

authorization_details

, and environment-provided access tokens may not expose grant metadata. Do not claim unreported permissions are present. If a stored session's grants cannot be verified, use

auth upgrade

with the required access. Do not replace an environment-provided session without asking the user.

列出所有命令：
```
link-cli --llms
```
列出带参数的所有命令：
```
link-cli --llms-full
```
使用
```
--schema
```
获取命令的精确结构。例如：
```
link-cli auth login --schema
```
多步骤命令会返回
```
_next
```
操作。例如，认证流程会返回
```
_next.command
```
，必须运行该命令才能完成流程。
默认所有输出为
```
toon
```
格式。传入
```
--format [json|md|yaml]
```
可更改输出格式。
部分命令会返回验证或批准URL。必须将这些URL清晰地展示给用户，以便其进行操作。
```
--auth <path>
```
标志用于将认证凭据存储到指定文件，而非默认位置。
```
auth login
```
会写入该文件；所有其他命令会从该文件读取凭据。示例：
```
link-cli auth login --auth credentials.json --format json
```

推荐操作：运行

link-cli --llms

了解所有可用命令。

--llms-full

的输出是参数名称、类型和有效值的权威参考。调用命令前传入

--schema

，以了解其参数和约束条件。

若返回结果中包含

scope

和

authorization_details

，请检查所选使用场景所需的访问权限。源操作会出现在

type: "source"

的授权详情中。若响应包含

update

字段，请运行其

update_command

，然后再次检查状态。

若无活跃会话，使用
```
auth login
```
。
若活跃会话已具备所需访问权限，请勿启动新的授权流程。
除非用户明确要求替换为更窄的访问权限，否则不要仅为添加权限而登出，保留已有的更广泛访问权限。

若用户已认证，但需要更广泛的访问权限（额外的

scope

、

--source-actions

或

--authorization-detail

），请使用

auth upgrade

而非

auth login

。它接受相同的标志，但不会因“已登录”而终止流程，而是将请求的权限与当前

scope

authorization_details

合并，并启动新的批准流程以获取权限的超集——因此现有访问权限永远不会被移除。请先检查

auth status

，了解已授予的权限。在批准过程中，当前会话保持有效，仅当用户批准新会话后才会替换，因此若用户放弃升级，现有会话仍可正常使用。

令牌端点可能省略

scope

或

authorization_details

，环境提供的访问令牌可能不暴露授权元数据。请勿声称存在未报告的权限。若无法验证存储会话的授权，请使用

auth upgrade

请求所需访问权限。未经用户同意，请勿替换环境提供的会话。

3. Request access for the use case

3. 根据使用场景请求访问权限

Use this access mapping:

Use case	Scopes	Source actions
Agent payments only	`userinfo:read payment_methods.agentic`	None
Financial insights only	`userinfo:read`	Actions required for the requested insights
Both	`userinfo:read payment_methods.agentic`	Actions required for the requested insights

Map financial-insight needs to source actions:

Intended insight	Source action
Link-processed transactions	`read_link_transactions`
Transactions imported from connected banks	`read_external_transactions`
Account balances	`read_balances`
Connected source details and descriptions	`read_source_details`

Request only the actions needed for a specific stated task. If the user asks to set up financial insights generally, request all four. For both, combine the agent-payment scopes with the applicable source actions.

Use

login

upgrade

based on the status result, a clear client name for the agent or application, and the scopes from the mapping:

bash

link-cli auth login \
  --client-name "<your-agent-name>" \
  --scope "<selected-scopes>" \
  --format json

Replace

<your-agent-name>

with the name of your agent or application (for example,

"Personal Assistant"

"Shopping Bot"

). This name appears in the user's Link app when they approve the connection. Use a clear, unique, identifiable name.

Change

login

upgrade

when widening an active session. For financial insights, add one

--source-actions <action>

flag per required action. Do not pass placeholders literally.

使用以下权限映射：

使用场景	权限范围（Scopes）	源操作（Source actions）
仅Agent支付	`userinfo:read payment_methods.agentic`	无
仅财务洞察	`userinfo:read`	所需洞察对应的操作
两者兼具	`userinfo:read payment_methods.agentic`	所需洞察对应的操作

将财务洞察需求映射到源操作：

预期洞察内容	源操作（Source action）
Link处理的交易记录	`read_link_transactions`
从关联银行导入的交易记录	`read_external_transactions`
账户余额	`read_balances`
关联源的详情与描述	`read_source_details`

仅请求特定任务所需的操作。若用户要求设置通用的财务洞察功能，请请求全部四个操作。对于两者兼具场景，将Agent支付的权限范围与适用的源操作组合。

根据状态结果，使用

login

或

upgrade

命令，指定清晰的Agent或应用客户端名称，以及映射中的权限范围：

bash

link-cli auth login \
  --client-name "<your-agent-name>" \
  --scope "<selected-scopes>" \
  --format json

将

<your-agent-name>

替换为你的Agent或应用名称（例如

"Personal Assistant"

、

"Shopping Bot"

）。该名称会在用户批准连接时显示在Link应用中，请使用清晰、唯一、易于识别的名称。

当需要扩大活跃会话的权限时，将

login

改为

upgrade

。对于财务洞察，每个所需操作添加一个

--source-actions <action>

标志。请勿直接使用占位符。

4. Complete user approval

4. 完成用户批准

Authorization is a multi-step flow:

Present the returned
```
verification_url
```
and phrase clearly to the user.
Run the returned
```
_next.command
```
immediately to poll for approval; do not wait for another user reply before polling.
Continue only when the result reports successful authentication and the required grants.

The response includes a

_next

command — run it to poll until authenticated. If your environment cannot relay the verification code while a separate polling command blocks I/O, use inline polling instead by adding

--interval 5 --timeout 300

to the initial

auth login

auth upgrade

command. This yields the code immediately then polls in the same command.

DO NOT PROCEED until the user is authenticated with Link.

If approval is denied, expires, or times out, report that outcome. Do not repeatedly create new authorization flows without the user's direction. Never expose access tokens, refresh tokens, or authentication-file contents.

授权是一个多步骤流程：

将返回的
```
verification_url
```
和短语清晰地展示给用户。
立即运行返回的
```
_next.command
```
以轮询批准状态；无需等待用户回复即可开始轮询。
仅当结果显示认证成功且已获得所需授权时，才可继续操作。

响应中包含

_next

命令——运行该命令以轮询直至认证完成。若你的环境无法在单独的轮询命令阻塞I/O时传递验证码，可通过在初始

auth login

或

auth upgrade

命令中添加

--interval 5 --timeout 300

来使用内联轮询。这样会立即返回验证码，然后在同一命令中进行轮询。

在用户完成Link认证前，请勿继续操作。

若批准被拒绝、过期或超时，请告知用户该结果。未经用户指示，请勿重复创建新的授权流程。切勿暴露访问令牌、刷新令牌或认证文件内容。

5. Hand off to the use-case skill

5. 转交至对应场景的Skill

Authentication alone does not authorize an individual purchase and does not answer a financial-data question.

For purchases and payment credentials, use the
```
create-payment-credential
```
skill.
For transactions, balances, sources, and summaries, use the
```
financial-insights
```
skill.
For users who selected both, load the relevant downstream skill for each subsequent task.

仅完成认证并不授权进行单独的购买操作，也无法回答财务数据相关问题。

对于购买和支付凭证，使用
```
create-payment-credential
```
Skill。
对于交易记录、账户余额、关联源和汇总信息，使用
```
financial-insights
```
Skill。
对于选择“两者兼具”的用户，针对后续每项任务加载相应的下游Skill。