@stripe/link-cli 0.4.2 → 0.5.0

package/README.md

@@ -1,6 +1,13 @@
 # Link CLI
 
-Link CLI lets agents get secure, one-time-use payment credentials from a Link wallet — so they can complete purchases on your behalf without ever storing your real card details.
+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:
+
+- 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)
+
+For now, this is only available to US Link accounts.
 
 ## Installation
 
@@ -14,11 +21,31 @@ Or run directly with `npx`:
 npx @stripe/link-cli
 ```
 
-You can install the skill via `npx skills add stripe/link-cli`.
+### Use with agents
+
+Install the skill:
+
+```bash
+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:
+
+```bash
+link-cli --llms-full
+```
+
+Get a command's full schema with `--schema`. Example:
 
-### MCP Server
+```bash
+link-cli spend-request create --schema
+```
+
+#### MCP Server
 
-Link CLI can also run as a local MCP server. Add the following to your MCP client config (`.mcp.json`, etc.)
+Link CLI can run as a local MCP server. Add the following to your MCP client config (`.mcp.json`, etc.)
 
 ```json
 {
@@ -33,6 +60,12 @@ Link CLI can also run as a local MCP server. Add the following to your MCP clien
 
 ## Quickstart
 
+Run a guided onboarding and demo flow:
+
+```bash
+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).
@@ -41,7 +74,7 @@ The `link-cli` requires a Link account. You can log in to your existing one or [
 link-cli auth login
 ```
 
-You'll 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.
+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.
 
 ### List payment methods
 
@@ -49,11 +82,19 @@ You'll receive a verification URL and a short phrase. Visit the URL, log in to y
 link-cli payment-methods list
 ```
 
-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, you can [add new ones in Link](https://app.link.com/wallet).
+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).
+
+### List shipping addresses
+
+```bash
+link-cli shipping-address list
+```
+
+Returns the shipping addresses saved to your Link account. The response preserves nullable `nickname`, `address`, and address fields exactly as returned by the API.
 
 ### Create a spend request
 
-To request a secure, one-time payment credential from your Link wallet, you create a spend request. You specify a payment method in your account, as well as some merchant details, line items, and amounts.
+Create a spend request with a payment method, merchant details, line items, and amounts:
 
 ```bash
 link-cli spend-request create \
@@ -67,9 +108,9 @@ link-cli spend-request create \
   --request-approval
 ```
 
-The `--request-approval` flag triggers a push notification (or email) 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.
 
-Users can easily approve requests with the [Link app](https://link.com/download).
+Easily approve requests with the [Link app](https://link.com/download).
 
 #### Line items and totals
 
@@ -81,7 +122,7 @@ Users can easily approve requests with the [Link app](https://link.com/download)
 --line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"
 ```
 
-**`--total` keys:** `type` (required), `display_text` (required), `amount` (required)
+**`--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" \
@@ -90,24 +131,32 @@ Users can easily approve requests with the [Link app](https://link.com/download)
 
 #### 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, you can instead include `--credential-type "shared_payment_token"`. 
+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"`. 
 
 ### 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. 
 
 ```bash
-link-cli spend-request retrieve lsrq_001 --format json
+link-cli spend-request retrieve lsrq_001
+```
+By default, retrieving a spend request doesn't include card details. Pass `--include card` to see unmasked card details.
+
+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):
+
+```bash
+link-cli spend-request retrieve lsrq_001 --include card --output-file /tmp/link-card.json --format json
 ```
-By default, retrieving a spend request will not include card details. Use the `--include=card` to see unmasked card details.
+
+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.
 
 For agent polling, pass `--interval` and optionally `--max-attempts`:
 
 ```bash
-link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 150 --format json
+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`, or `expired`. If polling reaches `--timeout` or exhausts `--max-attempts` 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.
+Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, `expired`, or `canceled`. If polling reaches `--timeout` or exhausts `--max-attempts` 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:
 
@@ -115,8 +164,7 @@ If the merchant supports MPP, use `link-cli mpp pay` instead:
 link-cli mpp pay https://climate.stripe.dev/api/contribute \
   --spend-request-id lsrq_001 \
   --method POST \
-  --data '{"amount":100}' \
-  --format json
+  --data '{"amount":100}'
 ```
 
 ## Advanced
@@ -124,14 +172,14 @@ link-cli mpp pay https://climate.stripe.dev/api/contribute \
 ### Authentication
 
 ```bash
-link-cli auth login --client-name "Claude Code" --format json   # identify the connecting agent
-link-cli auth status --format json                               # check auth status
-link-cli auth logout --format json                               # disconnect
+link-cli auth login --client-name "Claude Code"   # identify the connecting agent
+link-cli auth status                               # check auth status
+link-cli auth logout                               # disconnect
 ```
 
-When `--client-name` is provided, the name is shown in the Link app when the user approves the connection — e.g. `Claude Code on my-macbook` instead of `link-cli on my-macbook`.
+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`.
 
-`auth status --format json` includes an `update` field when a newer version is available:
+`auth status` includes an `update` field when a newer version is available:
 
 ```json
 {
@@ -144,7 +192,9 @@ When `--client-name` is provided, the name is shown in the Link app when the use
 }
 ```
 
-Set `NO_UPDATE_NOTIFIER=1` to suppress update checks (e.g. in CI).
+Set `NO_UPDATE_NOTIFIER=1` to suppress update checks (for example, in CI).
+
+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.
 
 ### Spend request lifecycle
 
@@ -153,57 +203,54 @@ A spend request moves through: **create** → **request approval** → **approve
 **Required fields for create:** `payment_method_id`, `merchant_name`, `merchant_url`, `context`, `amount`
 
 **Constraints:** `context` must be at least 100 characters; `amount` must not exceed 50000 (cents); `currency` must be a 3-letter ISO code.
-**Test mode:** Pass `--test` to create testmode credentials (uses test card `4242424242424242`). Useful for development and integration testing without using real payment methods.
+**Test mode:** Pass `--test` to create testmode credentials (uses test card `4242424242424242`), useful for development and integration testing without real payment methods.
 
 ```bash
 # Update before approval
 link-cli spend-request update lsrq_001 \
-  --merchant-url https://press.stripe.com/working-in-public \
-  --format json
+  --merchant-url https://press.stripe.com/working-in-public
 
 # Request approval separately (alternative to create --request-approval)
-link-cli spend-request request-approval lsrq_001 --format json
-
-# Retrieve at any time (includes card credentials once approved)
-link-cli spend-request retrieve lsrq_001 --format json
-```
+link-cli spend-request request-approval lsrq_001
 
-### Output formats
+# Retrieve at any time (includes card credentials after approval)
+link-cli spend-request retrieve lsrq_001
 
-All commands accept `--format json` for structured JSON output. Other formats: `yaml`, `md`, `jsonl`, `toon` (default). Errors are returned as JSON with `code` and `message` fields, with exit code 1.
+# Cancel a spend request (from created, pending_approval, or approved state)
+link-cli spend-request cancel lsrq_001
+```
 
 ### MPP
 
-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 be approved. The SPT is one-time-use — if payment fails, create a new spend 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.
 
 ```bash
 link-cli mpp pay https://climate.stripe.dev/api/contribute \
   --spend-request-id lsrq_001 \
   --method POST \
   --data '{"amount":100}' \
-  --header "X-Custom: value" \
-  --format json
+  --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:
 
 ```bash
 link-cli mpp decode \
-  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."' \
-  --format json
+  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
 ```
 
 ### Environment variables
 
 | Variable | Effect |
 |----------|--------|
+| `LINK_AUTH_FILE` | Same as `--auth` — override the auth credential file path (flag takes precedence) |
 | `LINK_API_BASE_URL` | Override the API base URL |
 | `LINK_AUTH_BASE_URL` | Override the auth base URL |
 | `LINK_HTTP_PROXY` | Route all requests through an HTTP proxy (requires `undici`) |
 
 ## Onboard
 
-Run the guided setup flow — authenticates, checks payment methods, shows the app download QR, and walks through both demo flows:
+Run the guided setup flow — authenticates, checks payment methods, shows the app download QR, and runs both demo flows:
 
 ```bash
 link-cli onboard