@stripe/link-cli 0.14.0 → 0.14.2

package/README.md

@@ -2,13 +2,38 @@
 
 Link CLI lets agents get secure, one-time-use payment credentials from a Link wallet to complete purchases on your behalf — without storing your real card details.
 
-The CLI can produce one of two credential types:
+The CLI can produce one of three credential types:
 
 - 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.
-- A [Shared Payment Token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) (SPT) when the seller accepts programmatic payments through [Machine Payment Protocols](https://mpp.dev) (MPP)
+- A Link Pay Token (LPT) for use with a Stripe hosted payment form. Stripe checkout pages expose an agent steering block that allows agents to complete the checkout.
+- 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)
 
 For now, this is only available to US Link accounts.
 
+Documentation:
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Advanced usage](#advanced)
+  - [Authentication](#authentication)
+  - [The spend request lifecycle](#spend-request-lifecycle)
+  - [Credential type: Shared Payment Token](#shared-payment-token)
+  - [Credential type: Link Pay Token](#link-pay-token)
+  - [Limits](#limits)
+  - [Reporting issues](#report-outcomes)
+  - [Handling step ups](#handle-step-ups)
+  - [Adding line items and totals](#line-items-and-totals)
+  - [Approval details](#approval-details)
+  - [Metadata](#metadata)
+  - [Environment variables](#environment-variables)
+- [Integrating into your agent](#integrating-into-agents)
+- [Onboarding and Demos](#onboarding-and-demos)
+- [Development](#development)
+- [Releasing](#releasing)
+
+> [!TIP]
+> 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).
+
 ## Installation
 
 ```bash
@@ -23,7 +48,7 @@ npx @stripe/link-cli
 
 ### Use with agents
 
-Install the skill:
+Install the skills:
 
 ```bash
 npx skills add stripe/link-cli
@@ -58,9 +83,7 @@ Link CLI can run as a local MCP server. Add the following to your MCP client con
 }
 ```
 
-#### HTTP MCP Server
-
-Use `serve` to expose link-cli as an MCP endpoint over HTTP. This is useful for remote or containerised agents that can't launch a local subprocess.
+Alternatively, use `serve` to expose link-cli as an MCP endpoint over HTTP.
 
 ```bash
 link-cli serve            # binds 127.0.0.1:54321 (loopback only)
@@ -80,7 +103,7 @@ link-cli onboard
 
 ### Login
 
-The `link-cli` requires a Link account. You can log in to your existing one or [register online](https://app.link.com).
+The `link-cli` requires a Link account. You can log in to your existing one or [create one online](https://app.link.com).
 
 ```bash
 link-cli auth login
@@ -120,88 +143,10 @@ link-cli spend-request create \
   --request-approval
 ```
 
-The `--request-approval` flag triggers a push notification to the user for approval, then polls until the request is approved or denied.
+The `--request-approval` flag triggers a push notification to the user for approval, then polls until the request is approved or denied. Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, `expired`, or `canceled`. 
 
 Easily approve requests with the [Link app](https://link.com/download).
 
-If the created spend request comes back with `status: "requires_action"`, no approval is needed yet — the payment method or account needs attention first. Check `status_details.requires_action.next_action` for `type`, `display_message`, `action_url`, and `resolution`. For 3D Secure (`resolution: "auto_resume"`), keep polling `spend-request retrieve` — the request resolves on its own once the challenge is completed. For any other resolution, complete the indicated action and create a new spend request.
-
-#### Line items and totals
-
-`--line-item` and `--total` use repeatable `key:value` format.
-
-**`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url`
-
-```bash
---line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"
-```
-
-**`--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)
-
-```bash
---total "type:subtotal,display_text:Subtotal,amount:12000" \
---total "type:total,display_text:Total,amount:12000"
-```
-
-#### Approval details
-
-For delegated/pre-approved flows, pass `--approval-detail` with a JSON object describing how the user approved the request. Required fields: `approved_at` (unix timestamp), `approval_method` (`click`, `programmatic`, or `voice`), `app_name`, `external_user_id`. Optional: `ip_address`, `user_agent`, `device_type` (`mobile` or `web`), `agent_log_id`, `external_user_name`, `external_session_id`, `authentication_method` (`biometric_face`, `biometric_fingerprint`, or `passkey`).
-
-In CLI mode, pass as a JSON string:
-
-```bash
-link-cli spend-request create ... \
-  --approval-detail '{"approved_at":1720000000,"approval_method":"click","app_name":"MyApp","external_user_id":"usr_123"}'
-```
-
-In MCP/agent mode, pass as a structured object.
-
-#### Metadata
-
-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.
-
-```bash
-link-cli spend-request create ... \
-  --metadata "order_id:ord_123" \
-  --metadata "team:growth"
-```
-
-In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
-
-#### Credential types
-
-By default, a spend request provisions a virtual card. 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"`. 
-
-#### Link Pay Token
-
-Some Stripe checkout pages expose an AI-agent steering block that supports a
-Link Pay Token (LPT). Inspect the checkout in a browser before creating the
-SpendRequest: enable the agent checkbox, then verify that both
-`input[name="link_pay_token"]` and
-`data-stripe-merchant-account="acct_..."` are present in the same Stripe
-frame.
-
-Create an LPT-bound request with the DOM-derived account ID. Do not pass
-`--merchant-name` or `--merchant-url`; Link resolves the canonical merchant
-identity from the account ID for the approval screen.
-
-```bash
-link-cli spend-request create \
-  --payment-method-id csmrpd_xxx \
-  --execution-method link_pay_token \
-  --merchant-account-id acct_... \
-  --context "Purchasing an item from the checkout the agent inspected. The user initiated this purchase through the shopping assistant." \
-  --amount 3500 \
-  --request-approval
-```
-
-LPT requests use the default `card` credential type and do not support
-`--test`, `--network-id`, or `shared_payment_token`. After approval, retrieve
-`--include link_pay_token` immediately before using it on the same checkout
-surface. Each returned LPT is valid for up to 30 minutes, or until the
-SpendRequest expires. If either DOM marker is absent, create a regular virtual
-card SpendRequest instead; do not create an LPT request.
-
 ### Execute payment
 
 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. 
@@ -225,17 +170,6 @@ For agent polling, pass `--interval` and optionally `--max-attempts`:
 link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 300
 ```
 
-Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, `expired`, or `canceled`. If the status becomes `requires_action`, behavior depends on `next_action.resolution`: `auto_resume` (used for 3D Secure) means polling continues automatically — the request resolves on its own once the user completes the challenge. Any other resolution stops polling immediately and the command exits with the `next_action` details instead of waiting for a terminal status; the caller must have the user act, then create a new spend request. If `--timeout` is reached or `--max-attempts` is exhausted while the request is still non-terminal, the command exits non-zero with `code: "POLLING_TIMEOUT"` so callers do not treat a still-pending request as complete.
-
-If the merchant supports MPP, use `link-cli mpp pay` instead:
-
-```bash
-link-cli mpp pay https://climate.stripe.dev/api/contribute \
-  --spend-request-id lsrq_001 \
-  --method POST \
-  --data '{"amount":100}'
-```
-
 ## Advanced
 
 ### Authentication
@@ -250,7 +184,7 @@ link-cli auth logout                               # disconnect
 
 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`.
 
-With `--interval`, the login command yields the verification code immediately and then polls inline until authenticated or timed 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.
+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.
 
 `auth upgrade` takes the same flags as `auth login` but is meant for widening access when you're already logged in. Unlike `auth login` — which stops with an "already logged in" message when a valid session exists — `auth upgrade` merges the flags you pass with your currently granted `scope` and `authorization_details` and starts a new approval for the **superset**, so you never accidentally drop access. If there's no valid session, it prints a warning and continues with just the access you requested. Your current session stays valid throughout the approval and is only replaced (and the old grant revoked) once you approve the new one — so abandoning the approval leaves your existing session untouched.
 
@@ -305,23 +239,22 @@ link-cli spend-request retrieve lsrq_001
 link-cli spend-request cancel lsrq_001
 ```
 
-### Limits
+### Credential types
 
-| Limit | Value |
-|-------|-------|
-| Max amount per spend request | $500 (50,000 cents) |
-| Approval window | 10 minutes — user must approve within 10 min of `request-approval` |
-| Card / SPT validity | 12 hours from spend request creation |
-| Daily spend | $500 |
-| Monthly spend (30 days) | $20,000 |
-| Concurrent active requests (created + approved) | 30 |
-| Concurrent approved requests | 10 |
-| Hourly creation rate | 50 per hour |
-| Rolling creation rate | 200 per 60 days |
+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) and a Link Pay Token (LPT) for use on Stripe hosted checkout forms.
+
+### Shared Payment Token
+
+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. The SPT is one-time-use — if payment fails, create a new spend request.
 
-### MPP
+Use `mpp decode` to validate a raw `WWW-Authenticate` header and extract the `network_id` needed for `shared_payment_token` spend requests:
+
+```bash
+link-cli mpp decode \
+  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
+```
 
-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. The SPT is one-time-use — if payment fails, create a new spend request.
+Use `mpp pay` to complete purchases: 
 
 ```bash
 link-cli mpp pay https://climate.stripe.dev/api/contribute \
@@ -331,13 +264,53 @@ link-cli mpp pay https://climate.stripe.dev/api/contribute \
   --header "X-Custom: value"
 ```
 
-Use `mpp decode` to validate a raw `WWW-Authenticate` header and extract the `network_id` needed for `shared_payment_token` spend requests:
+### Link Pay Token
+
+Some Stripe checkout pages expose an AI-agent steering block that supports a
+Link Pay Token (LPT). Inspect the checkout in a browser before creating the
+SpendRequest: enable the agent checkbox, then verify that both
+`input[name="link_pay_token"]` and
+`data-stripe-merchant-account="acct_..."` are present in the same Stripe
+frame.
+
+Create an LPT-bound request with the DOM-derived account ID. Do not pass
+`--merchant-name` or `--merchant-url`; Link resolves the canonical merchant
+identity from the account ID for the approval screen.
 
 ```bash
-link-cli mpp decode \
-  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
+link-cli spend-request create \
+  --payment-method-id csmrpd_xxx \
+  --execution-method link_pay_token \
+  --merchant-account-id acct_... \
+  --context "Purchasing an item from the checkout the agent inspected. The user initiated this purchase through the shopping assistant." \
+  --amount 3500 \
+  --request-approval
 ```
 
+LPT requests use the default `card` credential type and do not support
+`--test`, `--network-id`, or `shared_payment_token`. After approval, retrieve
+`--include link_pay_token` immediately before using it on the same checkout
+surface. Each returned LPT is valid for up to 30 minutes, or until the
+SpendRequest expires. If either DOM marker is absent, create a regular virtual
+card SpendRequest instead; do not create an LPT request.
+
+
+### Limits
+
+| Limit | Value |
+|-------|-------|
+| Max amount per spend request | $500 (50,000 cents) |
+| Approval window | 10 minutes — user must approve within 10 min of `request-approval` |
+| Card / SPT validity | 12 hours from spend request creation |
+| Daily spend | $500 |
+| Monthly spend (30 days) | $20,000 |
+| Concurrent active requests (created + approved) | 30 |
+| Concurrent approved requests | 10 |
+| Hourly creation rate | 50 per hour |
+| Rolling creation rate | 200 per 60 days |
+
+
+
 ### Report outcomes
 
 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.
@@ -357,6 +330,58 @@ link-cli report --domain shop.example.com --outcome abandoned --spend-request-id
 
 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`.
 
+
+
+### Handle step-ups 
+
+If the created spend request comes back with `status: "requires_action"`, no approval is needed yet — the payment method or account needs attention first. Check `status_details.requires_action.next_action` for `type`, `display_message`, `action_url`, and `resolution`.
+
+For 3D Secure (`resolution: "auto_resume"`), keep polling `spend-request retrieve` — the request resolves on its own once the challenge is completed. For any other resolution, complete the indicated action and create a new spend request.
+
+### Line items and totals
+
+Optionally pass additional data on the specific items being purchased, and any tax, shipping or other amounts.
+
+`--line-item` and `--total` use repeatable `key:value` format.
+
+**`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url`
+
+```bash
+--line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"
+```
+
+**`--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)
+
+```bash
+--total "type:subtotal,display_text:Subtotal,amount:12000" \
+--total "type:total,display_text:Total,amount:12000"
+```
+
+### Approval details
+
+For delegated/pre-approved flows, pass `--approval-detail` with a JSON object describing how the user approved the request. Required fields: `approved_at` (unix timestamp), `approval_method` (`click`, `programmatic`, or `voice`), `app_name`, `external_user_id`. Optional: `ip_address`, `user_agent`, `device_type` (`mobile` or `web`), `agent_log_id`, `external_user_name`, `external_session_id`, `authentication_method` (`biometric_face`, `biometric_fingerprint`, or `passkey`).
+
+In CLI mode, pass as a JSON string:
+
+```bash
+link-cli spend-request create ... \
+  --approval-detail '{"approved_at":1720000000,"approval_method":"click","app_name":"MyApp","external_user_id":"usr_123"}'
+```
+
+In MCP/agent mode, pass as a structured object.
+
+### Metadata
+
+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.
+
+```bash
+link-cli spend-request create ... \
+  --metadata "order_id:ord_123" \
+  --metadata "team:growth"
+```
+
+In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
+
 ### Environment variables
 
 | Variable | Effect |
@@ -369,7 +394,12 @@ Outcomes: `success`, `blocked`, `abandoned`. Tags: `stripe_checkout`, `captcha`,
 | `LINK_AUTH_BASE_URL` | Override the auth base URL |
 | `LINK_HTTP_PROXY` | Route all requests through an HTTP proxy (requires `undici`) |
 
-## Onboard
+## Integrating into agents
+
+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.), 
+please reach out to `danhill at stripe.com`. We can support higher limits, more embedded approval flows, and additional advanced capabilities.
+
+## Onboarding and Demos
 
 Run the guided setup flow — authenticates, checks payment methods, shows the app download QR, and runs both demo flows:
 
@@ -377,8 +407,6 @@ Run the guided setup flow — authenticates, checks payment methods, shows the a
 link-cli onboard
 ```
 
-## Demo
-
 Run an interactive demo of both Link payment flows (always uses test mode — no real charges):
 
 ```bash
@@ -416,35 +444,38 @@ pnpm biome check .
 
 ## Releasing
 
-This project uses [Changesets](https://github.com/changesets/changesets) to manage versioning and publishing. Only `@stripe/link-cli` is published to npm — internal packages (`@stripe/link-sdk`, `@stripe/link-typescript-config`) are ignored by changesets.
+This project uses [Changesets](https://github.com/changesets/changesets) to
+version and publish `@stripe/link-cli` and `@stripe/link-sdk`.
+`@stripe/link-typescript-config` is private and is not published.
 
 ### Add a changeset
 
-When you make a user-facing change, add a changeset before merging:
+Add a changeset for any user-facing change before merging:
 
 ```bash
 pnpm changeset
 ```
 
-Follow the prompts to select the package (`@stripe/link-cli`) and the semver bump type (patch, minor, or major). This creates a markdown file in `.changeset/` describing the change.
-
-### Version
+Select each affected public package and its semver bump. Commit the generated
+file in `.changeset/` with the change.
 
-Once changesets have accumulated on `main`, create a version PR:
-
-```bash
-pnpm changeset version
-```
+### Publish
 
-This consumes all pending changesets, bumps the version in `packages/cli/package.json`, and updates `CHANGELOG.md`.
+After changesets reach `main`, the release workflow creates or updates the
+**Version Packages** pull request. Review and merge that PR to publish the
+new package versions to npm. The workflow uses npm trusted publishing and
+generates provenance attestations for the SDK; no npm token or local publish
+command is needed.
 
-### Publish
+CLI releases also upload the bundled JavaScript, standalone executables, and
+checksums to the corresponding GitHub Release. SDK-only releases skip that CLI
+artifact work.
 
-After the version PR is merged:
+To inspect the packages without publishing them:
 
 ```bash
-pnpm run build
-pnpm changeset publish
+pnpm turbo run build
+pnpm --filter @stripe/link-cli --filter @stripe/link-sdk publish --dry-run --no-git-checks
 ```
 
-This publishes `@stripe/link-cli` to npm. CI also runs `pnpm --filter @stripe/link-cli publish --dry-run --no-git-checks` on every push to `main` to verify the package is publishable.
+CI runs the same publish dry-run for every pull request.

package/dist/cli.js

@@ -2798,6 +2798,9 @@ function buildHeaders(data, headers) {
     const value = line.slice(idx + 1).trim();
     if (key) result[key] = value;
   }
+  if (!Object.keys(result).some((key) => key.toLowerCase() === "user-agent")) {
+    result["User-Agent"] = `link-cli/${"0.14.2"}`;
+  }
   return result;
 }
 async function readPayResult(response) {
@@ -7577,7 +7580,7 @@ function cacheUpdateInfo(value, ttlMs = UPDATE_CACHE_TTL_MS) {
 }
 
 // src/cli.tsx
-var cliVersion = "0.14.0";
+var cliVersion = "0.14.2";
 var cliName = "@stripe/link-cli";
 var defaultHeaders = {
   "User-Agent": `link-cli/${cliVersion}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripe/link-cli",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "type": "module",
   "bin": {
     "link-cli": "./dist/cli.js"
@@ -45,7 +45,7 @@
     "tsx": "^4.23.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@stripe/link-sdk": "1.0.0",
+    "@stripe/link-sdk": "0.2.0",
     "@stripe/link-typescript-config": "0.0.0"
   },
   "scripts": {