@stripe/link-cli 0.4.3 → 0.6.0

package/README.md

@@ -58,6 +58,17 @@ 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.
+
+```bash
+link-cli serve            # listens on port 54321 by default
+link-cli serve --port 8080
+```
+
+The MCP endpoint is available at `/mcp` on the chosen port.
+
 ## Quickstart
 
 Run a guided onboarding and demo flow:
@@ -84,6 +95,14 @@ 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, [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
 
 Create a spend request with a payment method, merchant details, line items, and amounts:
@@ -114,7 +133,7 @@ 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; one of: `subtotal`, `tax`, `total`), `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" \
@@ -145,10 +164,10 @@ The file is created with `0600` permissions. If the file already exists, the com
 For agent polling, pass `--interval` and optionally `--max-attempts`:
 
 ```bash
-link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 150
+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:
 
@@ -165,12 +184,15 @@ link-cli mpp pay https://climate.stripe.dev/api/contribute \
 
 ```bash
 link-cli auth login --client-name "Claude Code"   # identify the connecting agent
+link-cli auth login --client-name "Claude Code" --interval 5 --timeout 300  # login + poll in one call
 link-cli auth status                               # check auth status
 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.
+
 `auth status` includes an `update` field when a newer version is available:
 
 ```json
@@ -186,13 +208,15 @@ When you provide `--client-name`, the Link app displays it when you approve the
 
 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
 
 A spend request moves through: **create** → **request approval** → **approved** (with credentials).
 
 **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.
+**Constraints:** `context` must be at least 100 characters; `amount` must not exceed 50000 (cents); `currency` must be a 3-letter ISO code. The user has 10 minutes from when approval is requested to approve. Approved credentials (card or SPT) are valid for 12 hours from spend request creation.
 **Test mode:** Pass `--test` to create testmode credentials (uses test card `4242424242424242`), useful for development and integration testing without real payment methods.
 
 ```bash
@@ -205,8 +229,24 @@ link-cli spend-request request-approval lsrq_001
 
 # Retrieve at any time (includes card credentials after approval)
 link-cli spend-request retrieve lsrq_001
+
+# Cancel a spend request (from created, pending_approval, or approved state)
+link-cli spend-request cancel lsrq_001
 ```
 
+### 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 |
+| Concurrent active requests (created + approved) | 30 |
+| Concurrent approved requests | 10 |
+| Hourly creation rate | 50 per hour |
+| Rolling creation rate | 200 per 60 days |
+
 ### 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 you must approve it before paying. The SPT is one-time-use — if payment fails, create a new spend request.
@@ -230,6 +270,10 @@ link-cli mpp decode \
 
 | Variable | Effect |
 |----------|--------|
+| `LINK_AUTH_FILE` | Same as `--auth` — override the auth credential file path (flag takes precedence) |
+| `LINK_ACCESS_TOKEN` | Use this access token directly, bypassing auth storage |
+| `LINK_REFRESH_TOKEN` | Refresh token to use when `LINK_ACCESS_TOKEN` is expired |
+| `LINK_NO_REFRESH` | When set, never auto-refresh the access token — error instead |
 | `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`) |