link-cli

Link CLI のセットアップ

ユーザーの想定する用途に合わせて、Link CLI をセットアップして認証します。セットアップ後、決済または金融インサイトに関する作業には専用のスキルを使用します。

1. 用途を判断する

ユーザーの意図が明確な場合に限り、用途を推測します。

• エージェントによる決済：購入、支払い、チェックアウト、または決済用認証情報の取得。
• 金融インサイト：取引、残高、連携済みアカウント、または支出パターンの確認。
• 両方：決済と金融インサイトの両方を有効にする。

想定される用途が不明確な場合は、インストール、認証、または権限の選択を行う前に、まず両方を提示し、既定の選択肢として明示的に推奨します。

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

ユーザーが既定の選択肢を尋ねた場合、推奨を受け入れた場合、または希望がない場合は、両方を選択します。それ以外の場合、ユーザーが用途を選択するか、意図を明確にするまで先に進まないでください。

2. 最初に認証を確認する

用途が決まったら、最初の Link CLI コマンドとして auth status を実行します。auth login、auth upgrade、決済関連コマンド、または金融データ関連コマンドの前に、必ず実行してください。

link-cli auth status --format json

link-cli が利用できない場合は、npm install -g @stripe/link-cli でインストールしてから、ステータスコマンドを実行します。代わりに、すべてのコマンドの link-cli を npx @stripe/link-cli@latest に置き換えることもできます。

一般的なコマンド／オプション

• すべてのコマンドを一覧表示：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 login ではなく auth upgrade を使用してください。同じフラグを受け付けますが、「すでにログインしています」というメッセージで停止する代わりに、要求した内容を現在の scope／authorization_details に統合し、より広範なアクセス権を対象とする新しい承認フローを開始します。そのため、既存のアクセス権が失われることはありません。すでに付与されているアクセス権を把握できるよう、まず auth status を確認してください。ユーザーが新しい承認を行うまで、現在のセッションは有効なままです。そのため、アップグレードを途中で中断しても、既存のセッションは引き続き使用できます。

トークンエンドポイントでは scope または authorization_details が省略されることがあります。また、環境変数から提供されたアクセストークンでは、付与されたアクセス権のメタデータが確認できない場合があります。報告されていない権限があると断言しないでください。保存済みセッションの権限を確認できない場合は、必要なアクセス権を指定して auth upgrade を使用してください。ユーザーに尋ねずに、環境変数から提供されたセッションを置き換えないでください。

3. ユースケースに必要なアクセスをリクエストする

次のアクセスマッピングを使用します。

ユースケース	スコープ	ソースアクション
エージェントによる支払いのみ	userinfo:read payment_methods.agentic	なし
金融インサイトのみ	userinfo:read	リクエストされたインサイトに必要なアクション
両方	userinfo:read payment_methods.agentic	リクエストされたインサイトに必要なアクション

金融インサイトのニーズをソースアクションに対応付けます。

意図するインサイト	ソースアクション
Link で処理された取引	read_link_transactions
接続済みの銀行からインポートされた取引	read_external_transactions
口座残高	read_balances
接続済みソースの詳細と説明	read_source_details

具体的に明示されたタスクに必要なアクションのみをリクエストしてください。ユーザーが金融インサイト全般の設定を求めている場合は、4 つすべてをリクエストしてください。両方の場合は、エージェントによる支払いのスコープと、該当するソースアクションを組み合わせてください。

ステータスの結果に応じて login または upgrade を使用し、エージェントまたはアプリケーションの名前を明確に指定して、マッピングに記載されたスコープを使用します。

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

<your-agent-name> をエージェントまたはアプリケーションの名前（例："Personal Assistant"、"Shopping Bot"）に置き換えてください。この名前は、ユーザーが接続を承認する際に Link アプリに表示されます。明確で、一意に識別できる名前を使用してください。

有効なセッションの範囲を拡大する場合は、login を upgrade に変更してください。金融インサイトの場合は、必要なアクションごとに --source-actions <action> フラグを 1 つ追加してください。プレースホルダーをそのまま渡さないでください。

4. ユーザーの承認を完了する

認証は複数の手順で行います。

1. 返された verification_url とフレーズを、ユーザーにはっきりと提示します。
2. 返された _next.command を直ちに実行して承認状態をポーリングします。ポーリングを始める前に、ユーザーからの次の返信を待たないでください。
3. 認証が成功し、必要な権限が付与されたことが結果で確認できた場合にのみ、先へ進みます。

ユーザーのメールアドレスがすでに分かっている場合は、URL エンコードした fromEmail クエリパラメーターとして、任意の app.link.com 検証 URL またはアクション URL に追加してください。既存のクエリパラメーターは保持してください。

応答には _next コマンドが含まれます。認証が完了するまでポーリングするために、このコマンドを実行してください。環境上、別のポーリングコマンドが I/O をブロックしている間に検証コードを中継できない場合は、最初の auth login または auth upgrade コマンドに --interval 5 --timeout 300 を追加して、インラインポーリングを使用してください。これにより、コードがすぐに表示され、同じコマンド内でポーリングも行われます。

ユーザーが Link で認証されるまで、先に進まないでください。

承認が拒否された場合、期限切れになった場合、またはタイムアウトした場合は、その結果を報告してください。ユーザーの指示なしに、新しい認証フローを繰り返し開始しないでください。アクセストークン、リフレッシュトークン、認証ファイルの内容は決して公開しないでください。

5. ユースケースに対応するスキルに引き継ぐ

認証だけでは、個別の購入は承認されず、金融データに関する質問への回答も得られません。

• 購入や支払い情報については、create-payment-credential スキルを使用してください。
• 取引、残高、ソース、概要については、financial-insights スキルを使用してください。
• 両方を選択したユーザーの場合は、その後の各タスクに応じたスキルを読み込んでください。