Skip to content
Back to search

link-cli

MarketplaceWorks with Claude CodeGitHub

Let your agents spend on your behalf. Your payment credentials are never exposed. You approve every purchase.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/stripe/link-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/stripe/link-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stripe-link-cli/badge.svg)](/listings/stripe-link-cli)

HTML

<a href="/listings/stripe-link-cli"><img src="/api/listings/stripe-link-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm i -g @stripe/link-cli

Or run directly with `npx`:

npx @stripe/link-cli

Use with agents

Install the skills:

npx skills add stripe/link-cli

By default when called from an agent (non-TTY), all commands use `toon` output — a compact, LLM-friendly text format. All commands accept `--format [format]` for structured output. Other formats: `json`, `yaml`, `md`, `jsonl`.

List available commands:

link-cli --llms-full

Get a command's full schema with `--schema`. Example:

link-cli spend-request create --schema

MCP Server

Link CLI can run as a local MCP server. Add the following to your MCP client config (`.mcp.json`, etc.)

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

Alternatively, use `serve` to expose link-cli as an MCP endpoint over HTTP.

link-cli serve            # binds 127.0.0.1:54321 (loopback only)
link-cli serve --port 8080
link-cli serve --host 0.0.0.0   # expose beyond localhost (see warning below)

The server handles `POST /mcp` and `GET` skill discovery at `/.well-known/skills/index.json` and `/.well-known/skills/{skill-name}/SKILL.md`, with `OPTIONS` preflight support. Other paths return `404`, unsupported methods return `405`, and malformed or ambiguous request paths return `400`. It binds to `127.0.0.1` by default so only the local host can reach it. Anyone who can reach the port can use this CLI's authenticated Link session, so only override `--host` on a trusted, isolated network — doing so prints a warning.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 40 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "link-cli",
  3. "owner": {
  4. "name": "Stripe",
  5. "email": "agent-spend@stripe.com"
  6. },
  7. "metadata": {
  8. "description": "Secure, one-time-use payment credentials from Link"
  9. },
  10. "plugins": [
  11. {
  12. "name": "link",
  13. "source": "./plugins/link",
  14. "description": "Authenticate with Link, create spend requests, and retrieve one-time-use card or shared payment token credentials for user-approved purchases.",
  15. "author": {
  16. "name": "Stripe"
  17. },
  18. "homepage": "https://link.com/agents",
  19. "repository": "https://github.com/stripe/link-cli",
  20. "license": "MIT",
  21. "category": "finance",
  22. "tags": [
  23. "payments",
  24. "wallet",
  25. "checkout",
  26. "credentials",
  27. "stripe",
  28. "link"
  29. ],
  30. "keywords": [
  31. "payments",
  32. "wallet",
  33. "checkout",
  34. "credentials",
  35. "stripe",
  36. "link"
  37. ]
  38. }
  39. ]
  40. }
README.md · README · 1,080 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Link CLI
  2. Link CLI lets agents get secure payment credentials from a Link wallet for one-time purchases and recurring payments — without storing your real card details.
  3. The CLI can produce one of three credential types:
  4. - A virtual card (PAN) for use with a standard web checkout form. The issued card works anywhere, and is not restricted to Link-enabled sellers or sellers that use Stripe.
  5. - A Link Pay Token (LPT) for use on supported Stripe payment surfaces. Stripe checkout pages use WebMCP to allow agents to complete the checkout.
  6. - A [Shared Payment Token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) (SPT) for use when the seller accepts programmatic payments through [Machine Payment Protocols](https://mpp.dev) (MPP)
  7. For now, this is only available to US and Canadian Link accounts.
  8. Documentation:
  9. - [Installation](#installation)
  10. - [Quickstart](#quickstart)
  11. - [Where to use Link Agent Wallet](#where-to-use-link-agent-wallet)
  12. - [Advanced usage](#advanced)
  13. - [Authentication](#authentication)
  14. - [The spend request lifecycle](#spend-request-lifecycle)
  15. - [Recurring payments](#recurring-payments)
  16. - [Credential type: Shared Payment Token](#shared-payment-token)
  17. - [Credential type: Link Pay Token](#link-pay-token)
  18. - [Limits](#limits)
  19. - [Reporting issues](#report-outcomes)
  20. - [Handling step ups](#handle-step-ups)
  21. - [Adding line items and totals](#line-items-and-totals)
  22. - [Metadata](#metadata)
  23. - [Environment variables](#environment-variables)
  24. - [Integrating into your agent](#integrating-into-agents)
  25. - [SDKs](#sdks)
  26. - [Onboarding and Demos](#onboarding-and-demos)
  27. - [Development](#development)
  28. - [Releasing](#releasing)
  29. > [!TIP]
  30. > If you're looking to integrate the Link CLI into your product or agent for consumers to pay with, be sure to look at [Integrating into your agent](#integrating-into-agents).
  31. ## Installation
  32. ```bash
  33. npm i -g @stripe/link-cli
  34. ```
  35. Agent and plugin integrations, including the MCP server, run the installed `link-cli` binary. They intentionally never download or resolve packages at startup, so install the CLI first.
  36. ### Use with agents
  37. Install the skills:
  38. ```bash
  39. npx skills add stripe/link-cli
  40. ```
  41. By default when called from an agent (non-TTY), all commands use `toon` output — a compact, LLM-friendly text format. All commands accept `--format [format]` for structured output. Other formats: `json`, `yaml`, `md`, `jsonl`.
  42. List available commands:
  43. ```bash
  44. link-cli --llms-full
  45. ```
  46. Get a command's full schema with `--schema`. Example:
  47. ```bash
  48. link-cli spend-request create --schema
  49. ```
  50. #### MCP Server
  51. Link CLI can run as a local MCP server. Add the following to your MCP client config (`.mcp.json`, etc.)
  52. ```json
  53. {
  54. "mcpServers": {
  55. "link": {
  56. "command": "link-cli",
  57. "args": ["--mcp"]
  58. }
  59. }
  60. }
  61. ```
  62. Alternatively, use `serve` to expose link-cli as an MCP endpoint over HTTP.
  63. ```bash
  64. link-cli serve # binds 127.0.0.1:54321 (loopback only)
  65. link-cli serve --port 8080
  66. link-cli serve --host 0.0.0.0 # expose beyond localhost (see warning below)
  67. link-cli serve --allow-origin http://localhost:3000 # trust a specific browser app
  68. ```
  69. The server handles `POST /mcp` and `GET` skill discovery at `/.well-known/skills/index.json` and `/.well-known/skills/{skill-name}/SKILL.md`, with `OPTIONS` preflight support. Other paths return `404`, unsupported methods return `405`, and malformed or ambiguous request paths return `400`. It binds to `127.0.0.1` by default so only the local host can reach it. Anyone who can reach the port can use this CLI's authenticated Link session, so only override `--host` on a trusted, isolated network — doing so prints a warning.
  70. A browser attaches an `Origin` header; MCP clients and `curl` do not. Because any JavaScript on any `http://localhost:*` page the user visits would satisfy a bare "loopback origin" check without being the authenticated CLI owner, `serve` **rejects every browser `Origin` by default** (`403`, no CORS header) and validates the `Host` header against loopback to block DNS rebinding. Requests without an `Origin` (ordinary MCP clients) are unaffected. To integrate a browser app you control, allow its exact origin with `--allow-origin` (repeatable); only that origin is reflected in `Access-Control-Allow-Origin`.
  71. ## Quickstart
  72. Run a guided onboarding and demo flow:
  73. ```bash
  74. link-cli onboard
  75. ```
  76. ### Login
  77. The `link-cli` requires a Link account. You can log in to your existing one or [create one online](https://app.link.com).
  78. ```bash
  79. link-cli auth login
  80. ```
  81. You receive a verification URL and a short phrase. Visit the URL, log in to your Link account, and enter the phrase to approve the connection.
  82. By default, login requests the `userinfo:read` and `payment_methods.agentic`
  83. scopes plus the four financial-insights source actions. To leave out financial
  84. data access, use `--no-financial-insights`; to leave out payment access, use
  85. `--no-agentic-payments`.
  86. ### Retrieve user info
  87. ```bash
  88. link-cli user-info retrieve --format json
  89. ```
  90. In addition to identity fields, the response can include the user's address,
  91. balance eligibility, spend limits, and verification requirements:
  92. ```json
  93. {
  94. "email": "jane@example.com",
  95. "name": "Jane Doe",
  96. "address": {
  97. "line1": "510 Townsend St",
  98. "line2": null,
  99. "city": "San Francisco",
  100. "state": "CA",
  101. "postal_code": "94103",
  102. "country": "US"
  103. },
  104. "eligible_for_balance": true,
  105. "agent_wallet_spend_limits": {
  106. "per_transaction": { "limit": 50000 },
  107. "daily": { "limit": 500000, "used": 120000, "remaining": 380000 },
  108. "thirty_day": { "limit": null, "used": 600000, "remaining": null }
  109. },
  110. "agent_wallet_verification_requirement": {
  111. "status": "identity_verification",
  112. "action_url": "https://app.link.com/finish_setup?verify=identity_verification&intended_email=jane%40example.com&fromEmail=jane%40example.com"
  113. }
  114. }
  115. ```
  116. The address and `eligible_for_balance` fields are omitted when their enrichment
  117. is unavailable. `address` is null when the user has no Person record.
  118. `eligible_for_balance` reports balance eligibility for the user and the current
  119. OAuth app; an absent field does not establish eligibility or ineligibility.
  120. Finite spend-limit values are cents because this response does not include a
  121. currency. A null limit or remaining amount means unlimited.
  122. `agent_wallet_verification_requirement.status` can be
  123. `not_required`, `ssn_verification`, `credit_file_match_ca`,
  124. `identity_verification`, `doc_upload_ca`, `pending`, `contact_support`, or
  125. `complete`. Its `action_url` is null when no user action is available.
  126. ### Retrieve approval policy
  127. Retrieve the rules that grant the current app authority to create spend requests
  128. without manual approval:
  129. ```bash
  130. link-cli approval-policy retrieve --format json
  131. ```
  132. Each rule includes an action, a per-purchase limit, and optionally an ordered
  133. list of allowed payment method IDs. The API returns an error when no approval
  134. policy has been configured.
  135. ### List payment methods
  136. ```bash
  137. link-cli payment-methods list
  138. ```
  139. Returns the cards and bank accounts saved to your Link account. Use the `id` field as `payment_method_id` in the next step. If you have no payment methods, [add new ones in Link](https://app.link.com/wallet).
  140. The list can also include a Link balance payment method with its available
  141. balance when that amount is available.
  142. Retrieve one payment method by ID:
  143. ```bash
  144. link-cli payment-methods retrieve <payment-method-id>
  145. ```
  146. The response contains the same redacted fields as the matching list item,
  147. including capability eligibility when available.
  148. Set or change a payment-method nickname:
  149. ```bash
  150. link-cli payment-methods update <payment-method-id> --nickname "Work card"
  151. ```
  152. Clear a nickname by passing an explicit empty string:
  153. ```bash
  154. link-cli payment-methods update <payment-method-id> --nickname ""
  155. ```
  156. Set a payment method as the wallet default, or clear its default status:
  157. ```bash
  158. link-cli payment-methods update <payment-method-id> --is-default true
  159. link-cli payment-methods update <payment-method-id> --is-default false
  160. ```
  161. You can pass `--nickname` and `--is-default` together. Supply at least one of
  162. them; omitted fields stay unchanged. Setting a new default replaces the previous
  163. wallet default. Link trims surrounding nickname whitespace and returns the
  164. updated, redacted payment method.
  165. ### List shipping addresses
  166. ```bash
  167. link-cli shipping-address list
  168. ```
  169. Returns the shipping addresses saved to your Link account. The response preserves nullable `nickname`, `address`, and address fields exactly as returned by the API.
  170. ### Create a spend request
  171. Create a spend request with merchant details, line items, and amounts. If `--payment-method-id` is omitted, your default payment method will be used, or the first eligible one if no default is set:
  172. ```bash
  173. link-cli spend-request create \
  174. --payment-method-id csmrpd_xxx \
  175. --merchant-name "Stripe Press" \
  176. --merchant-url "https://press.stripe.com" \
  177. --context "Purchasing 'Working in Public' from press.stripe.com. The user initiated this purchase through the shopping assistant." \
  178. --amount 3500 \
  179. --line-item "name:Working in Public,unit_amount:3500,quantity:1" \
  180. --total "type:total,display_text:Total,amount:3500" \
  181. --request-approval
  182. ```
  183. The `--request-approval` flag triggers a push notification to the user for approval. Interactive mode polls until the request leaves the approval waiting states. Agent mode returns a `spend-request retrieve` command to wait for a status change, including a transition to `submitted`.
  184. Easily approve requests with the [Link app](https://link.com/download).
  185. ### Execute payment
  186. The approved spend request includes a `card` object with `number`, `cvc`, `exp_month`, `exp_year`, `billing_address`, and `valid_until`. Enter these into the merchant's checkout form.
  187. ```bash
  188. link-cli spend-request retrieve lsrq_001
  189. ```
  190. By default, retrieving a spend request doesn't include card details. Pass `--include card` to see unmasked card details.
  191. To avoid leaking card credentials into agent transcripts or logs, use `--output-file` to write the full card to a secure local file while stdout shows only redacted data (brand, last4, expiry):
  192. ```bash
  193. link-cli spend-request retrieve lsrq_001 --include card --output-file /tmp/link-card.json --format json
  194. ```
  195. The file is created with `0600` permissions. If the file already exists, the command fails unless `--force` is passed. When `--output-file` is set, the JSON output replaces the `card` object with redacted fields and adds a `card_output_file` path.
  196. To inspect only the existing user action in one snapshot:
  197. ```bash
  198. link-cli spend-request retrieve lsrq_001 --next-action --format json
  199. ```
  200. This returns one JSON result item, `[{"next_action": <server action or null>}]`, including actions on `requires_action` and `failed` requests. It does not poll or return credentials. `--include`, `--output-file`, `--force`, and nonzero `--interval`/`--max-attempts` are incompatible; `--timeout` is ignored. Human TTY invocations require an explicit format. Use ordinary retrieve to inspect status or poll.
  201. For agent polling, pass `--interval` and optionally `--max-attempts`:
  202. ```bash
  203. link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 300
  204. ```
  205. ## Where to use Link Agent Wallet
  206. Link is already integrated with the following agents:
  207. - [Muse by Meta](https://muse.ai)
  208. - [Grok Bot](https://x.ai/bot)
  209. - [Instinct](https://instinct.com)
  210. - [Browser Use](https://browser-use.com/)
  211. ## Financial Insights
  212. Link CLI can also read a consumer's financial data -- transactions, balances, and connected account details. Agents can use these features to answer personal finance questions and track trends. Financial Insights are powered by [Financial Connections](https://stripe.com/financial-connections), covering 12,000+ US financial institutions.
  213. Financial Insights also provides pre-computed and user-provided insights to power better shopping experiences through the `insights` commands.
  214. ### Authentication
  215. `auth login` requests all four financial-insights source actions by default:
  216. `read_link_transactions`, `read_external_transactions`, `read_balances`, and
  217. `read_source_details`. The user decides whether to approve the connection;
  218. requesting access does not retrieve financial data.
  219. ```bash
  220. link-cli auth login --client-name "My Agent"
  221. ```
  222. Use `--no-financial-insights` for a payment-only login, or
  223. `--no-agentic-payments` for a login without the default payment scope. To
  224. request a narrower set of financial-data actions, pass the desired
  225. `--source-actions` flags or `--authorization-detail` entries; either replaces
  226. the four-action default. Don't combine either option with an explicit
  227. `--financial-insights` or `--no-financial-insights` flag. An explicit `--scope`
  228. replaces the default scopes. If already authenticated, use
  229. `auth upgrade --source-actions <action>` to add only the access needed without
  230. dropping existing access.
  231. Discovering available insight types only requires an authenticated session. Retrieving an insight can require additional source actions, which the discovery response identifies.
  232. #### Discover and list user-supplied and pre-aggregated insights
  233. ```bash
  234. link-cli insights list-available-types --format json
  235. link-cli insights list --insight <insight_id> --format json
  236. ```
  237. The first command lists available insight IDs, descriptions, and any access needed to retrieve them. The second returns the selected insight's status and data. Omit `--insight` to list all insights, or repeat it for several IDs to request only a few. Both commands support `--limit` and `--starting-after` to retrieve paginated results. If the provided access token is insufficient to view an insight, a `no_data` result will include `authorization_remediation` for missing permissions. A `pending` result means the insight is still being computed.
  238. #### List sources
  239. ```bash
  240. link-cli sources list
  241. ```
  242. Returns connected financial accounts (bank accounts, credit cards, etc.) with metadata, capabilities, and connection status. Use the `id` field as `--source` in other commands.
  243. #### List transactions
  244. ```bash
  245. link-cli transactions list
  246. ```
  247. Supports server-side filtering:
  248. ```bash
  249. link-cli transactions list --start-date 2026-01-01 --end-date 2026-01-31
  250. link-cli transactions list --category groceries
  251. link-cli transactions list --origin external_connection
  252. link-cli transactions list --source <source_id>
  253. ```
  254. | Flag | Description |
  255. | ---- | ---- |
  256. | `--start-date` | Only transactions on or after this date (YYYY-MM-DD) |
  257. | `--end-date` | Only transactions on or before this date (YYYY-MM-DD) |
  258. | `--category` | Filter by transaction category |
  259. | `--origin` | `link` (Link-native) or `external_connection` (from linked bank/card) |
  260. | `--source` | Filter by source ID (repeatable for multiple accounts) |
  261. | `--limit` | Max results per page (1–100) |
  262. Amounts are integers in the currency's smallest unit. Negative = money leaving the account, positive = money entering. Transactions may be Link-native (processed directly through Link), or sourced through an external connection (e.g. imported from transactions that would appear on a bank statement).
  263. #### Agent integration
  264. The financial-insights skill teaches agents which command to run for each question type, how to handle pagination, interpret amounts, and summarize results. See skills/financial-insights/SKILL.md for the full agent guide.
  265. #### List balances
  266. ```bash
  267. link-cli balances list
  268. link-cli balances list --source <source_id>
  269. ```
  270. Returns current balances for connected accounts, including `cash.available` (bank/savings) or `credit.used` (credit cards).
  271. ## Advanced
  272. ### Authentication
  273. ```bash
  274. link-cli auth login --client-name "Claude Code" # identify the connecting agent
  275. link-cli auth login --client-name "Claude Code" --interval 5 --timeout 300 # login + poll in one call
  276. link-cli auth upgrade --scope "userinfo:read" # widen access to a superset
  277. link-cli auth status # check auth status
  278. link-cli auth logout # disconnect
  279. ```
  280. When you provide `--client-name`, the Link app displays it when you approve the connection — for example, `Claude Code on my-macbook` instead of `link-cli on my-macbook`.
  281. With `--interval`, the login command yields the verification code immediately and then polls inline until authenticated or time out — no separate `auth status` call needed. This is recommended for agents that cannot relay the code while a separate polling command blocks their I/O channel.
  282. `auth upgrade` accepts the same explicit access flags as `auth login`, but does
  283. not add the login-only financial-insights default. Use it to widen an existing
  284. session. `auth login` stops with an "already logged in" message when a valid
  285. session exists; `auth upgrade` merges the requested access with the current
  286. `scope` and `authorization_details` and starts approval for the superset.
  287. If there is no valid session, `auth upgrade` warns and continues with only the
  288. requested access. An existing session remains valid during approval and is
  289. replaced only after the new grant is approved, so abandoning the approval leaves
  290. the old session working.
  291. `auth status` reports the `scope` and `authorization_details` the current session was granted (echoed by the token endpoint at login/refresh and stored in the credential file), and includes an `update` field when a newer version is available:
  292. ```json
  293. {
  294. "authenticated": true,
  295. "scope": "userinfo:read payment_methods.agentic",
  296. "authorization_details": [{ "type": "source", "actions": ["read"] }],
  297. "update": {
  298. "current_version": "0.1.2",
  299. "latest_version": "0.2.0",
  300. "update_command": "npm install -g @stripe/link-cli"
  301. }
  302. }
  303. ```
  304. `scope` and `authorization_details` are only present when the token endpoint returned them.
  305. Set `NO_UPDATE_NOTIFIER=1` to suppress update checks (for example, in CI).
  306. All commands accept `--auth <path>` 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. Useful for running multiple sessions with separate identities.
  307. ### Identity (beta)
  308. Services can verify these credentials with [Agent Identity](packages/agent-identity/README.md), a separate SDK in this repository. The [event-registration example](packages/agent-identity/example/step-up/README.md) shows site access using an attestation and registration using a verified email.
  309. Identity commands require Link Agent Wallet v0.27.0 or later for the flow documented here. Check `link-cli --version`; install or update with `npm install -g @stripe/link-cli@latest`. They are available in `--help` and `--llms` without a preview flag, but remain excluded from MCP. See [wallet setup](https://link.com/agents#get-started-section) and the [identity skill](skills/use-link-identity/SKILL.md).
  310. Both identity `request` commands save their artifacts to disk and return only the file path and metadata. This applies to every output format, including JSON, piped output, and `--full-output`. Request output never includes credentials, tokens, or claim values.
  311. **Privacy-preserving attestations** that let a service verify Link issued the token, without disclosing personal details or identifying the agent:
  312. ```bash
  313. link-cli identity attestations request --count 10
  314. ```
  315. Each request adds tokens to the CLI-managed pool at `~/.link-cli/identity/attestations/pool.json`. Pop one token when you need to answer an attestation challenge:
  316. ```bash
  317. link-cli identity attestations pop --format json
  318. ```
  319. `pop` removes one token before returning its `token`, ready-to-use `authorization` header, issuer, and issuer-key ID. Pass `authorization` as the `Authorization` header in your browser automation or HTTP client. An empty pool returns `ATTESTATION_POOL_EMPTY`; refill it with `request --count 10`.
  320. For agent-managed tokens, export a batch to a new file outside the CLI storage directory:
  321. ```bash
  322. link-cli identity attestations request --count 10 --output-file ./aats.json
  323. ```
  324. Exported tokens never enter the CLI pool. The agent owns their consumption and cleanup. Existing exports remain separate and are never automatically imported. Wallet credentials keep their existing storage and behavior.
  325. Pool updates are serialized and saved atomically. A crash after removal can lose a token; `pop` never returns it to the pool. If a crash leaves `pool.json.lock`, ensure no attestation commands are running before removing that lock directory.
  326. **User info that has been signed, proving it comes from Link**:
  327. ```bash
  328. link-cli identity credentials request
  329. ```
  330. `identity credentials request` saves a signed credential to `~/.link-cli/identity/credentials/current.json`, bound to the CLI-managed holder key at `~/.link-cli/identity/holder-key.jwk`. Structured output includes `output_file`, issuer, expiry, holder-key path/thumbprint, and claim names. Use `identity credentials present` to sign selected claims, capture its JSON output programmatically, and send the presentation through browser automation or an HTTP client without printing it into the agent transcript.
  331. **Presentations** disclose selected claims to a verifier using the saved credential and holder key:
  332. ```bash
  333. link-cli identity credentials present \
  334. --aud https://directory.example \
  335. --nonce '<nonce-from-challenge>' \
  336. --claim email \
  337. --format json
  338. ```
  339. ```json
  340. {"presentation":"<issuer-jwt>~<email-disclosure>~<key-binding-jwt>"}
  341. ```
  342. Use the verifier challenge's exact audience and nonce. Repeat `--claim` to disclose additional claims, such as `--claim email --claim email_verified`; at least one claim is required. The command reads `~/.link-cli/identity/credentials/current.json`, signs with its saved holder key, and returns only the presentation. It works without login or network access and does not modify the saved credential or key. Missing claims, expired credentials, mismatched keys, and unsupported disclosure formats fail instead of producing a presentation. It supports Link's flat SHA-256 disclosures; credentials with plaintext user claims or nested selective disclosures are rejected.
  343. Send the returned `presentation` as the `Identity-Presentation` HTTP header.
  344. The verifier still validates the issuer signature, holder signature, audience, nonce, expiry, and required claims. Presentations include a fresh signing time and should be sent promptly. Follow the service's retry instructions. Completed interactions may return a saved result; a new operation or expired interaction may require a fresh challenge. The Agent Identity SDK verifies nonce equality; the service manages interaction state and replay policy.
  345. **Local inspection** uses the same MCP exclusion:
  346. ```bash
  347. link-cli identity credentials list --format json
  348. link-cli identity attestations list --format json
  349. ```
  350. These commands inspect local files without login or Link API calls and display metadata in both terminal and structured output. Credential inspection reports the saved `~/.link-cli/identity/credentials/current.json` path, issuer, cached expiry/`expired` status, holder-key path/thumbprint, and claim names. Private keys are never opened; credentials, tokens, and claim values are never printed. Inspection does not modify files, verify signatures, or filter artifacts by the active account.
  351. Attestation inspection reports paths, issuer/key identifiers, per-batch `stored_token_count`, aggregate `total_token_count`, and `storage` (`pool` or `export`) for JSON batches in `~/.link-cli/identity/attestations`. Counts describe stored tokens; external usage is untracked and AATs have no embedded expiry. Empty stores return empty lists. Lists include per-file `errors` alongside valid entries.
  352. ### Spend request lifecycle
  353. A spend request moves through: **create** → **request approval** → **approved** (with credentials).
  354. **Required fields for a regular card create:** `merchant_name`, `merchant_url`,
  355. `context`, and `amount`. `payment_method_id` is optional — if omitted,
  356. your default payment method will be used, or the first eligible one if no
  357. default is set. Shared Payment Token requests instead require `network_id`;
  358. Link Pay Token requests require `credential_type=link_pay_token` and the
  359. DOM-derived `merchant_account_id`, and Link supplies their canonical merchant
  360. identity. Card requests may also include `--network-id` to identify the merchant's
  361. network profile.
  362. **Constraints:** `context` must be at least 100 characters; `amount` is an integer in the currency's smallest unit (e.g. cents) and must not exceed 50000 USD cents equivalent; `currency` can be any supported 3-letter ISO code. The user has 30 minutes from when approval is requested to approve.
  363. Omitting currency uses the consumer's default spend-request currency, reported by
  364. `userinfo.default_spend_request_currency` (`user-info retrieve` in the CLI).
  365. Specify currency explicitly when using an amount from a checkout with a known
  366. currency. Amounts, line-item `unit_amount` values, and total `amount` values use
  367. the selected currency's minor units: `100` means ¥100 in JPY or $1 in USD.
  368. The client passes amounts through unchanged and performs no FX conversion.
  369. This default applies to newly created requests; existing requests retain their
  370. stored currency.
  371. #### Expiration and delayed merchant charges
  372. Use `spend-request create --expires-at <timestamp>` to set the expiry,
  373. including in direct CLI integrations. Accepts Unix seconds or an ISO 8601
  374. timestamp ending in `Z` (UTC), such as `2027-02-01T12:00:00Z`. The CLI converts
  375. ISO input to integer Unix seconds for the API. This option can only be set at
  376. creation.
  377. ```bash
  378. # Allow a preorder charge for up to 90 days.
  379. EXPIRES_AT=$(node -e 'console.log(Math.floor(Date.now() / 1000) + 90 * 86400)')
  380. link-cli spend-request create \
  381. --merchant-name "Example Shop" \
  382. --merchant-url "https://shop.example.com" \
  383. --amount 4200 --currency usd \
  384. --context 'Preorder the selected book for $42 including tax and shipping. The merchant will charge when the book ships within 90 days.' \
  385. --expires-at "$EXPIRES_AT"
  386. ```
  387. `expires_at` is the spend request's expiry. The API uses integer Unix seconds;
  388. the CLI and SDK responses convert it to an ISO 8601 timestamp ending in `Z`
  389. (UTC), such as `"2027-02-01T12:00:00Z"`. Set it when the merchant may charge
  390. later, such as for a preorder, booking, or payment due after delivery. Choose a deadline that covers
  391. the expected charge date and explain the timing in `context`. Omit it for an
  392. ordinary purchase.
  393. This supports deferred authorization: for eligible card flows, Link can wait
  394. to fund the payment until the merchant charges. The merchant controls charge
  395. timing; `expires_at` does not schedule a payment.
  396. The server applies these limits when creating a request:
  397. - One-time requests default to 7 days and allow an explicit expiry up to 365 days.
  398. - Recurring requests default to their maximum, up to 1,827 days (about 5 years).
  399. Set an earlier expiry to end the spending permission sooner. `recurring`
  400. controls the spending-limit reset period; `expires_at` controls its end date.
  401. - An explicit expiry must be at least 3 hours in the future. Country limits
  402. apply to both request types: Japan is capped at 180 days, and an unknown
  403. account country uses a 180-day cap. The API validates the applicable limit.
  404. Approval is still required within 30 minutes of requesting it. A later
  405. `expires_at` does not extend that approval window.
  406. Follow the normal approval flow and check the current request status and
  407. returned credential `valid_until` before use. A later request expiry does not
  408. guarantee payment: funds and payment-method checks can still fail when the
  409. merchant charges. It also does not make a one-time SPT reusable.
  410. #### Completion callbacks
  411. For an application-owned return destination, supply `--completion-callback-url`
  412. and `--nonce` together when creating a request. Both are optional; supplying only
  413. one is rejected locally. The callback must be a valid URL of at most 2,048
  414. characters. The nonce must be nonblank and at most 512 JavaScript/UTF-16 code
  415. units. The API enforces live-mode HTTPS and URL security rules.
  416. Generate an opaque, unpredictable nonce, save it unchanged, and verify an exact
  417. match when your application receives the callback:
  418. ```bash
  419. NONCE="$(openssl rand -hex 32)"
  420. link-cli spend-request create \
  421. --amount 5000 \
  422. --currency usd \
  423. --context "The user asked to purchase the selected item from Example Store for $50, including all shipping costs and taxes." \
  424. --merchant-name "Example Store" \
  425. --merchant-url "https://example.com" \
  426. --completion-callback-url "https://agent.example.com/link/callback" \
  427. --nonce "$NONCE"
  428. ```
  429. Use the returned `approval_url` and `status_details.requires_action.next_action.action_url`
  430. as-is. When creation-time callback context is supplied, do not manually append
  431. callback parameters. A callback does not establish approval; retrieve the spend
  432. request and check its status before continuing.
  433. **Test mode:** Pass `--test` to create a testmode SpendRequest. A testmode SpendRequest will return test payment credentials (e.g test card `4000009990001984`) rather than a real payment credential. Testmode SpendRequests will not charge the underlying payment method of the SpendRequest. This is useful for development and integration testing without real payment methods.
  434. ```bash
  435. # Update before approval
  436. link-cli spend-request update lsrq_001 \
  437. --merchant-url https://press.stripe.com/working-in-public
  438. # Request approval separately (alternative to create --request-approval)
  439. link-cli spend-request request-approval lsrq_001
  440. # Retrieve a request; request a credential only when needed
  441. link-cli spend-request retrieve lsrq_001
  442. # Cancel a spend request (from created, pending_approval, or approved state)
  443. link-cli spend-request cancel lsrq_001
  444. ```
  445. Use `spend-request retrieve <id> --interval 2` to wait for the initial status
  446. to change. Polling starts only for `created`, `pending_approval`, or
  447. `requires_action` with an `auto_resume` resolution. Other statuses, including
  448. `submitted` and unfamiliar API values, return immediately. A change to another
  449. waiting status also returns; inspect the result and retrieve again as needed.
  450. If `--timeout` or `--max-attempts` is reached without a change, the command exits
  451. non-zero with `POLLING_TIMEOUT`.
  452. ### Recurring payments
  453. For a subscription or other recurring purchase, confirm the spending limit and
  454. cadence with the user, then add `--recurring-interval` when creating the request:
  455. ```bash
  456. link-cli spend-request create \
  457. --credential-type card \
  458. --merchant-name "Example Pro" \
  459. --merchant-url "https://example.com/subscribe" \
  460. --amount 2000 \
  461. --currency usd \
  462. --recurring-interval month \
  463. --context "Monthly access to Example Pro requested by the user, with a spending limit of $20 per month including all taxes."
  464. ```
  465. Supported intervals are `day`, `week`, `month`, and `year`.
  466. `--recurring-interval-count` is a positive integer and defaults to `1` on the
  467. server. For example, `--recurring-interval week --recurring-interval-count 2`
  468. resets the limit every two weeks. The count requires an interval. Omit both
  469. flags for a one-time purchase.
  470. For recurring requests, `--amount` is the spending limit per period, in the
  471. currency's minor units. It is not the total budget for the subscription's
  472. lifetime. The merchant controls billing; the CLI does not schedule charges.
  473. The same recurring options are available with `card`, `shared_payment_token`,
  474. and `link_pay_token`; each credential type keeps its merchant targeting and
  475. checkout requirements. Link enforces availability and applicable limits.
  476. Approval and credential retrieval use the normal flow. Responses include
  477. `recurring.interval` and `recurring.interval_count`; `spend-request list` also
  478. shows the cadence. Recurring card requests remain active after individual
  479. charges. Do not wait for the request to become `succeeded` after each payment
  480. or create a new request for each period. Confirm each payment from the
  481. merchant's result or transaction records.
  482. Recurring terms are set at creation; `spend-request update` does not change
  483. the interval or count. Respect the returned credential expiry.
  484. To stop future use of the payment credential, run
  485. `link-cli spend-request cancel <id>` and check the result. This revokes the
  486. credential; it does not cancel the subscription with the merchant. Complete
  487. the merchant's cancellation flow when the user asks to cancel the subscription.
  488. ### Credential types
  489. By default, a spend request provisions a virtual card. Link can also provide a shared payment token (SPT) for use with the Machine Payment Protocol (MPP) or a Link Pay Token (LPT) for supported Stripe payment surfaces. LPT is a distinct credential type.
  490. ### Shared Payment Token
  491. For merchants that support the [Machine Payments Protocol](https://mpp.dev) (HTTP 402) and the Stripe payment method, instead pass `--credential-type "shared_payment_token"` when creating the spend request. SPTs for one-time requests are single use; a consumed token requires a new spend request.
  492. For recurring SPTs, `usage_limits.max_amount` is the spending limit per period.
  493. The available spending amount resets to this limit each new period, as defined
  494. by `recurring.interval` and `recurring.interval_count`.
  495. Use `mpp decode` to validate a raw `WWW-Authenticate` header and extract the `network_id` needed for `shared_payment_token` spend requests:
  496. ```bash
  497. link-cli mpp decode \
  498. --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
  499. ```
  500. Use `mpp pay` to complete purchases:
  501. ```bash
  502. link-cli mpp pay https://climate.stripe.dev/api/contribute \
  503. --spend-request-id lsrq_001 \
  504. --method POST \
  505. --data '{"amount":100}' \
  506. --header "X-Custom: value"
  507. ```
  508. ### Link Pay Token
  509. Some Stripe payment surfaces expose an AI-agent steering block that supports a
  510. Link Pay Token (LPT). Inspect the checkout in a browser before creating the
  511. SpendRequest: find the `.AiAgentPaymentSteering` block and verify that both
  512. `input[name="link_pay_token"]` and
  513. `data-stripe-merchant-account="acct_..."` are present in the same Stripe
  514. frame.
  515. Create an LPT-bound request with the DOM-derived account ID. Do not pass
  516. `--merchant-name` or `--merchant-url`; Link resolves the canonical merchant
  517. identity from the account ID for the approval screen.
  518. ```bash
  519. link-cli spend-request create \
  520. --credential-type link_pay_token \
  521. --merchant-account-id acct_... \
  522. --payment-method-id csmrpd_xxx \
  523. --context "Purchasing an item from the checkout the agent inspected. The user initiated this purchase through the shopping assistant." \
  524. --amount 3500 \
  525. --request-approval
  526. ```
  527. LPT requests do not support `--test`, `--network-id`, merchant name, or merchant
  528. URL. After approval, retrieve `--include link_pay_token` immediately before
  529. using it on the same checkout surface. Each returned LPT is valid for up to 30
  530. minutes, or until the SpendRequest expires. If either DOM marker is absent,
  531. create a regular virtual card SpendRequest instead; do not create an LPT
  532. request.
  533. ### Limits
  534. | Limit | Value |
  535. |-------|-------|
  536. | Max amount per spend request | $500 (50,000 cents) |
  537. | Approval window | 30 minutes — user must approve within 30 min of `request-approval` |
  538. | Spend request expiry (`expires_at`) | 7 days by default for one-time requests; up to 365 days one-time or 1,827 days recurring, subject to country limits |
  539. | Credential validity | Check returned `valid_until` and current request status |
  540. | Daily spend | $500 |
  541. | Monthly spend (30 days) | $20,000 |
  542. | Concurrent active requests (created + approved) | 30 |
  543. | Concurrent approved requests | 10 |
  544. | Hourly creation rate | 50 per hour |
  545. | Rolling creation rate | 200 per 60 days |
  546. Dollar limits are enforced as the USD equivalent for spend requests in other currencies.
  547. Use `mpp pay` to complete purchases on merchants that use the [Machine Payments Protocol](https://mpp.dev). The spend request must use `credential_type: "shared_payment_token"` and you must approve it before paying. Requests created by `mpp pay` are for one-time payments; consumed SPTs require a new spend request.
  548. ```bash
  549. link-cli mpp pay https://climate.stripe.dev/api/contribute \
  550. --spend-request-id lsrq_001 \
  551. --method POST \
  552. --data '{"amount":100}' \
  553. --header "X-Custom: value"
  554. ```
  555. In agent mode (`--format json`), the full flow returns `_next.pay_argv` (`{ "command": "mpp", "args": [...] }`) to complete payment. If the new spend request is already approved, it omits polling instructions and `_next.poll_argv`. Otherwise, it also returns `_next.poll_argv` to wait for approval before paying. Invoke continuations directly without a shell. `command` is a Link CLI subcommand, not an executable; pass it and each `args` entry as separate arguments to your trusted CLI entrypoint:
  556. ```js
  557. import { execFile } from 'node:child_process';
  558. const { command, args } = result._next.pay_argv;
  559. // cliScript is the trusted path to the installed CLI's dist/cli.js.
  560. execFile(process.execPath, [cliScript, command, ...args], { shell: false });
  561. ```
  562. For the standalone Windows executable, use `execFile(cliExecutable, [command, ...args], { shell: false })`. Avoid npm `.cmd` shims, which require a command shell. Never join, unquote, or re-split an argv array to construct a shell string: URLs, request bodies, and headers can contain merchant-controlled text.
  563. Outside Windows, `_next.pay_command` and `_next.poll_command` remain available with `_next.shell: "posix"`. These strings are quoted **only for POSIX-compatible shells**; pass them verbatim only to such a shell, regardless of where the output was generated. They are unsafe for `cmd.exe` and PowerShell and are omitted on Windows.
  564. Spend-request approval and automatic-resume polling similarly return `_next.argv`. UCP checkout creation returns `_next.argv` as a completion template: after approval, replace only the `<spend_request_id>` argument with the approved ID, preserve the original business argument, and invoke the CLI directly. Do not execute the template before replacement or edit its compatibility string. These flows retain `_next.command` with `_next.shell: "posix"` outside Windows and omit the string on Windows.
  565. Use `mpp decode` to validate a raw `WWW-Authenticate` header and extract the `network_id` needed for `shared_payment_token` spend requests:
  566. ```bash
  567. link-cli mpp decode \
  568. --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
  569. ```
  570. ### UCP checkout
  571. All UCP commands show an interactive summary when run in a terminal without a format flag. Add `--format json` to any catalog or checkout command to return the full JSON response, including messages, fulfillment choices, capability metadata, and other returned fields. Use this flag for scripts and agents. Other explicit formats remain supported; piped output and MCP use structured output.
  572. Checkout summaries show buyer details, UCP messages (including error codes, severity, field paths, and recovery URLs), and selected fulfillment destinations and options. Available fulfillment choices remain in JSON output. Missing buyer details, destinations, or shipping selections are shown explicitly.
  573. Search a catalog, then use the returned business and SKU to create a UCP checkout:
  574. ```bash
  575. link-cli ucp catalog search --query "running shoes" --format json
  576. link-cli ucp checkout create --business <business> \
  577. --line-item 'id:<sku>' \
  578. --buyer 'first_name:Jane,email:jane@example.com,phone_number:+1234567890' \
  579. --fulfillment '{"methods":[{"type":"shipping","destinations":[{"street_address":"123 Main St","address_locality":"Springfield","address_region":"IL","postal_code":"62701","address_country":"US"}]}]}' \
  580. --format json
  581. ```
  582. `--line-item` is repeatable; `quantity` defaults to 1. All buyer fields are optional (`first_name`, `last_name`, `email`, `phone_number`). `--fulfillment` accepts the entire UCP JSON object; `--fullfilment` is an alternate spelling. Omit buyer to use saved Link buyer details during creation. Omitted fulfillment uses a complete saved default shipping address when available; a saved address that is not marked as default is not selected automatically. The seller determines the checkout currency.
  583. Review the returned `messages`, `totals`, and fulfillment choices. Update the checkout as needed.
  584. ```bash
  585. link-cli ucp checkout retrieve --id <checkout_id> --business <business> --format json
  586. link-cli ucp checkout update --id <checkout_id> --business <business> \
  587. --buyer 'email:jane@example.com' \
  588. --fulfillment '<entire fulfillment JSON object>' --format json
  589. ```
  590. Once the checkout is `ready_for_complete`, create and approve a `shared_payment_token` spend request for the final `totals` entry with `type: "total"`, using the business as its `--network-id`. Pass the approved request ID to complete the checkout:
  591. ```bash
  592. link-cli ucp checkout complete <checkout_id> --business <business> \
  593. --spend-request-id <spend_request_id> --format json
  594. ```
  595. Use `checkout retrieve` to check the checkout's current status. Checkout commands use the UCP API's live flow. Only catalog search supports `--test` demo results.
  596. To cancel a checkout, supply its ID and business. The response contains the canceled checkout:
  597. ```bash
  598. link-cli ucp checkout cancel --id <checkout_id> --business <business> --format json
  599. ```
  600. ### Report outcomes
  601. Use `report` to record the outcome of a purchase attempt. Reporting is optional, but calling it after attempts — success or failure — helps Stripe improve checkout for agents.
  602. ```bash
  603. # Successful purchase
  604. link-cli report --domain shop.example.com --outcome success --spend-request-id lsrq_abc123
  605. # Blocked by captcha
  606. link-cli report --domain shop.example.com --outcome blocked --spend-request-id lsrq_abc123 \
  607. --tag captcha --step "checkout page" --freeform-context "Turnstile challenge appeared"
  608. # Abandoned due to timeout
  609. link-cli report --domain shop.example.com --outcome abandoned --spend-request-id lsrq_abc123 \
  610. --tag timeout
  611. # With a step-by-step account of the path taken
  612. link-cli report --domain shop.example.com --outcome success --spend-request-id lsrq_abc123 \
  613. --attempt-trace '1. / — clicked "Shop" → category grid
  614. 2. /checkout — email required before shipping unlocks; entered [email]
  615. 3. /checkout — clicked "Pay now" → order confirmed'
  616. ```
  617. Outcomes: `success`, `blocked`, `abandoned`. Tags: `stripe_checkout`, `captcha`, `anti_bot_script`, `cdn_block`, `waf_block`, `dns_block`, `rate_limited`, `login_required`, `3ds_challenge`, `page_inaccessible`, `timeout`, `site_error`, `payment_declined`, `other`.
  618. `--step` records where the agent was when the outcome occurred. `--attempt-trace` is the whole path: one numbered line per step, each giving the URL path, the label acted on, the action, and the observed result, so another agent can follow it. Send it on failures too — the dead ends are the useful part. Omit the buyer's personal data and write `[email]`, `[address]` in its place. Over 8000 characters is truncated by the server rather than rejected, so send the full narrative instead of skipping the report.
  619. ### Handle step-ups
  620. Actions can appear at creation or on later retrieves, under `status_details.requires_action.next_action` or `status_details.failed.next_action`. Inspect the current action with:
  621. ```bash
  622. link-cli spend-request retrieve lsrq_001 --next-action --format json
  623. ```
  624. The JSON output is an array containing one projected result, for example:
  625. ```json
  626. [
  627. {
  628. "next_action": {
  629. "type": "ssn_verification",
  630. "resolution": "create_new_spend_request_after_completion",
  631. "display_message": "Additional identity verification is required.",
  632. "action_url": "https://example.com/verify?step=ssn",
  633. "expires_at": null
  634. }
  635. }
  636. ]
  637. ```
  638. Values come from the server; the example URL is synthetic. The action's expiry is a string or null, and older responses may omit it. `[{"next_action": null}]` means no action is exposed in this snapshot; it does not establish approval or rule out later verification. A missing/inaccessible request still returns an error. Snapshot mode neither forces verification nor completes or approves a request, and adds no continuation instructions.
  639. Show the server's message and exact non-null URL to the user, who completes verification themselves. Follow `resolution`: for `auto_resume`, keep the same request and inspect it after each user completion. A Visa OTP action can become `partner_create_card_enrollment` without changing status or URL. Use another snapshot or ordinary retrieve without polling to inspect the latest action; ordinary retrieve with `--interval` waits for status changes. For `create_new_spend_request` or `create_new_spend_request_after_completion`, follow the indicated action and user-completion requirements, then create a new request. Never attempt to resume a terminal failed request.
  640. ### Line items and totals
  641. Optionally pass additional data on the specific items being purchased, and any tax, shipping or other amounts.
  642. `--line-item` and `--total` use repeatable `key:value` format.
  643. **`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url`
  644. ```bash
  645. --line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"
  646. ```
  647. **`--total` keys:** `type` (required; one of: `subtotal`, `tax`, `total`, `items_base_amount`, `items_discount`, `discount`, `fulfillment`, `shipping`, `fee`, `gift_wrap`, `tip`, `store_credit`), `display_text` (required), `amount` (required)
  648. ```bash
  649. --total "type:subtotal,display_text:Subtotal,amount:12000" \
  650. --total "type:total,display_text:Total,amount:12000"
  651. ```
  652. ### Metadata
  653. Attach arbitrary string data to a spend request with the repeatable `--metadata` flag (`key:value` format). Max 50 keys, key ≤ 40 chars, value ≤ 500 chars.
  654. ```bash
  655. link-cli spend-request create ... \
  656. --metadata "order_id:ord_123" \
  657. --metadata "team:growth"
  658. ```
  659. In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
  660. ### Environment variables
  661. | Variable | Effect |
  662. |----------|--------|
  663. | `LINK_AUTH_FILE` | Same as `--auth` — override the auth credential file path (flag takes precedence) |
  664. | `LINK_ACCESS_TOKEN` | Use this access token directly, bypassing auth storage |
  665. | `LINK_REFRESH_TOKEN` | Refresh token to use when `LINK_ACCESS_TOKEN` is expired |
  666. | `LINK_NO_REFRESH` | When set, never auto-refresh the access token — error instead |
  667. | `LINK_API_BASE_URL` | Override the API base URL |
  668. | `LINK_AUTH_BASE_URL` | Override the auth base URL |
  669. | `LINK_HTTP_PROXY` | Route all requests through an HTTP proxy (requires `undici`) |
  670. ### Testing agent handling with sample spend-request responses
  671. `spend-request simulate` is opt-in engineering evaluation tooling. Log in with
  672. `link-cli auth login` or configure `LINK_ACCESS_TOKEN` first. It currently returns
  673. local fixtures; a backend provider will replace them after the endpoints land.
  674. It creates no spend request, verification session, OTP, approval, or account change.
  675. ```bash
  676. link-cli spend-request simulate --scenario ssn_verification --format json
  677. link-cli spend-request simulate --scenario visa_otp --format json
  678. link-cli spend-request simulate --list-scenarios --format json
  679. ```
  680. Choose exactly one selector. Use discovery for available IDs and aliases.
  681. `visa_otp` currently aliases `partner_auth_challenge`. Samples yield one
  682. `{"next_action": ...}` object (or null) inside the JSON array; discovery yields one
  683. `{"catalog_version": 1, "data": [...]}` object. The warning goes to stderr.
  684. Synthetic URLs under `example.invalid` cannot complete verification. Null/absent
  685. URLs still require presenting the message; a null overall action proves no approval.
  686. The evaluation controller selects scenarios. Present the exact URL/message and
  687. follow `resolution`: `auto_resume` keeps the same request;
  688. `create_new_spend_request` describes a new request;
  689. `create_new_spend_request_after_completion` requires user completion first;
  690. `reauthorize_with_additional_scope` describes obtaining the required scope without
  691. inventing an auth URL or executing an auth upgrade during evaluation. Never use
  692. simulation as a fallback when a real payment fails. It is excluded from MCP discovery.
  693. The backend transport has not shipped: local fixture results do not establish
  694. backend availability, authentication scope enforcement, or a real lifecycle.
  695. The later backend provider must report an unavailable endpoint as an error and
  696. must not fall back to fixtures. See the [engineering guide](packages/cli/src/commands/spend-request/SIMULATION.md)
  697. for the catalog and evaluation/transition checks.
  698. ## Integrating into agents
  699. If you are building an agent and want to offer Link as a native experience to your consumers (as a connector, plugin, pre-installed capability etc.),
  700. please look at our [documentation and steps for integrating](https://docs.link.com). We can support higher limits, more embedded approval flows, and additional capabilities.
  701. ## SDKs
  702. For services accepting agents, [Agent Identity](packages/agent-identity/README.md) verifies Link attestations and identity presentations. The wallet API clients below obtain credentials and call Link APIs.
  703. Applications can use the credential-only Link client directly in
  704. [TypeScript](packages/sdk/README.md), [Go](packages/sdk-go/README.md), or
  705. [Python](packages/sdk-python/README.md). The Python SDK provides synchronous and
  706. asynchronous clients covering the Go SDK's API resources with Python conventions.
  707. Authentication flows and credential persistence remain the embedding
  708. application's responsibility.
  709. The TypeScript SDK also exports reusable [agent tools](packages/sdk/README.md#agent-tools).
  710. Use the [Eve extension](packages/integrations/eve/README.md) to mount them in an
  711. Eve agent with a static access token or an application-provided Eve auth provider,
  712. plus a wallet skill.
  713. Use the [Mastra integration](packages/integrations/mastra/README.md) for native
  714. wallet tools, per-call token resolution, and spend confirmation. The
  715. [Mastra Studio example](packages/integrations/mastra/example/README.md) runs locally.
  716. ## Onboarding and Demos
  717. Run the guided setup flow — authenticates, checks payment methods, shows the app download QR, and runs both demo flows:
  718. ```bash
  719. link-cli onboard
  720. ```
  721. Run an interactive demo of both Link payment flows (always uses test mode — no real charges):
  722. ```bash
  723. link-cli demo # shows menu to choose flow
  724. link-cli demo --only-card # virtual card flow only
  725. link-cli demo --only-spt # machine payment (SPT) flow only
  726. ```
  727. ## Development
  728. Workspace development requires Node.js 24+.
  729. ```bash
  730. pnpm install
  731. pnpm run build
  732. pnpm run link-cli --help
  733. ```
  734. Watch mode:
  735. ```bash
  736. pnpm run dev
  737. ```
  738. Run tests:
  739. ```bash
  740. pnpm run test
  741. ```
  742. This runs the TypeScript, Go, and Python suites. Go SDK development requires Go
  743. 1.23 or newer. Python SDK development uses [uv](https://docs.astral.sh/uv/) and
  744. requires Python 3.11 or newer; uv can install the interpreter for you.
  745. ```bash
  746. uv python install 3.11
  747. uv sync --directory packages/sdk-python --locked
  748. pnpm run test:python
  749. pnpm run check:python
  750. ```
  751. Type-check and lint:
  752. ```bash
  753. pnpm run typecheck
  754. pnpm biome check .
  755. ```
  756. ## Releasing
  757. This project uses [Changesets](https://github.com/changesets/changesets) to
  758. version and publish the CLI, SDK, and integration packages, including
  759. `@stripe/link-integrations-mastra`.
  760. `@stripe/link-typescript-config` is private and is not published.
  761. ### Add a changeset
  762. Add a changeset for any user-facing change before merging:
  763. ```bash
  764. pnpm changeset
  765. ```
  766. Select each affected public package and its semver bump. Commit the generated
  767. file in `.changeset/` with the change.
  768. ### Publish
  769. After changesets reach `main`, the release workflow creates or updates the
  770. **Version Packages** pull request. Review and merge that PR to publish the
  771. new package versions to npm. The workflow uses npm trusted publishing and
  772. generates provenance attestations for the SDK; no npm token or local publish
  773. command is needed.
  774. CLI releases also upload the bundled JavaScript, standalone executables, and
  775. checksums to the corresponding GitHub Release. SDK-only releases skip that CLI
  776. artifact work.
  777. To inspect the packages without publishing them:
  778. ```bash
  779. pnpm turbo run build
  780. pnpm --filter @stripe/link-cli --filter @stripe/link-sdk --filter @stripe/link-integrations-better-auth --filter @stripe/link-integrations-eve --filter @stripe/link-integrations-mastra --filter @stripe/agent-identity publish --dry-run --no-git-checks
  781. ```
  782. CI runs the same publish dry-run for every pull request.
  783. The Go SDK is a nested module and is released with a repository tag such as
  784. `packages/sdk-go/v0.1.0`. Go module tags are independent of npm package
  785. versions.
  786. The Python SDK is published to PyPI as `stripe-link-sdk` using GitHub OIDC Trusted
  787. Publishing, with attestations for its wheel and source distribution. Its
  788. versions are independent of npm and Go: update `project.version` in
  789. `packages/sdk-python/pyproject.toml`, refresh `uv.lock`, and add Python changelog
  790. notes in a PR. Merging to `main` publishes an unpublished version automatically
  791. after the Python checks pass. See the [Python release guide](packages/sdk-python/README.md#releasing)
  792. for one-time PyPI setup, verification, and recovery.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.