Docs, skill improvements 2026-05-03 (#68)

* WIP

* fix totals schema type

* Improve copy with dante

* fix: formatting

* fix: minor path fix

* fix: correctly handle update notifier in TTY and non-TTY modes

* fix: update package to correct

* fix: formatting

* fix: improve update notifier

Author: danhill-stripe

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:
+
+```bash
+link-cli spend-request create --schema
+```
 
-### MCP Server
+#### 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,19 +74,19 @@ 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
 
 ```bash
 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).
 
 ### 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 +100,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 +114,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`), `display_text` (required), `amount` (required)
 
 ```bash
 --total "type:subtotal,display_text:Subtotal,amount:12000" \
@@ -90,21 +123,21 @@ 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 will not include card details. Use the `--include=card` to see unmasked card details.
+By default, retrieving a spend request doesn't include card details. Pass `--include card` to see unmasked card details.
 
 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 150
 ```
 
 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.
@@ -115,23 +148,22 @@ 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
 
 ### 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 +176,7 @@ 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).
 
 ### Spend request lifecycle
 
@@ -153,44 +185,37 @@ 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
+link-cli spend-request request-approval lsrq_001
 
-# Retrieve at any time (includes card credentials once approved)
-link-cli spend-request retrieve lsrq_001 --format json
+# Retrieve at any time (includes card credentials after approval)
+link-cli spend-request retrieve lsrq_001
 ```
 
-### Output formats
-
-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.
-
 ### 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
@@ -203,7 +228,7 @@ link-cli mpp decode \
 
 ## 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

package.json

@@ -10,7 +10,7 @@
     "lint": "biome lint .",
     "format": "biome format --write .",
     "check": "biome check --write .",
-    "link-cli": "node packages/cli/dist/cli.js"
+    "link-cli": "./packages/cli/dist/cli.js"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

packages/cli/src/cli.tsx

@@ -1,12 +1,16 @@
 import { Cli } from 'incur';
-import updateNotifier from 'update-notifier';
 import { createAuthCli } from './commands/auth';
 import { createDemoCli } from './commands/demo';
 import { createMppCli } from './commands/mpp';
 import { createOnboardCli } from './commands/onboard';
 import { createPaymentMethodsCli } from './commands/payment-methods';
 import { createSpendRequestCli } from './commands/spend-request';
 import { ResourceFactory } from './utils/resource-factory';
+import {
+  createAgentUpdateInfoProvider,
+  createInteractiveUpdateInfoProvider,
+  renderInteractiveUpdateNotice,
+} from './utils/update-info';
 
 declare const __CLI_VERSION__: string;
 declare const __BUILD_NUMBER__: string;
@@ -25,17 +29,29 @@ const factory = new ResourceFactory({ verbose, defaultHeaders });
 const authRepo = factory.createAuthResource();
 const spendRequestRepo = factory.createSpendRequestResource();
 
-const notifier = updateNotifier({
-  pkg: { name: cliName, version: cliVersion },
-});
-
 const cli = Cli.create('link-cli', {
   description:
     'Create a secure, one-time payment credential from a Link wallet to let agents complete purchases on behalf of users.',
   version: `${cliVersion} (build ${buildNumber})`,
 });
 
-cli.command(createAuthCli(authRepo, notifier.update));
+const isAgent =
+  process.argv.includes('--format') || process.argv.includes('--mcp');
+const agentUpdateInfoProvider = createAgentUpdateInfoProvider(
+  cliName,
+  cliVersion,
+);
+let getUpdateInfo = agentUpdateInfoProvider;
+
+if (!isAgent && process.stdout.isTTY) {
+  const updateInfo = await agentUpdateInfoProvider({ polling: false });
+  getUpdateInfo = createInteractiveUpdateInfoProvider(updateInfo);
+  if (updateInfo) {
+    process.stderr.write(renderInteractiveUpdateNotice(updateInfo));
+  }
+}
+
+cli.command(createAuthCli(authRepo, getUpdateInfo));
 cli.command(createSpendRequestCli(spendRequestRepo));
 cli.command(
   createPaymentMethodsCli(() => factory.createPaymentMethodsResource()),
@@ -52,12 +68,6 @@ cli.command(
   ),
 );
 
-const isAgent =
-  process.argv.includes('--format') || process.argv.includes('--mcp');
-if (!isAgent) {
-  notifier.notify({ defer: false });
-}
-
 cli.serve();
 
 export default cli;

packages/cli/src/commands/auth/index.tsx

@@ -3,14 +3,15 @@ import { Cli } from 'incur';
 import { render } from 'ink';
 import React from 'react';
 import type { IAuthResource } from '../../auth/types';
+import type { UpdateInfoProvider } from '../../utils/update-info';
 import { Login } from './login';
 import { Logout } from './logout';
 import { loginOptions, statusOptions } from './schema';
 import { AuthStatus } from './status';
 
 export function createAuthCli(
   authResource: IAuthResource,
-  updateInfo?: { current: string; latest: string },
+  getUpdateInfo?: UpdateInfoProvider,
 ) {
   const cli = Cli.create('auth', {
     description: 'Authentication commands',
@@ -103,6 +104,21 @@ export function createAuthCli(
     options: statusOptions,
     outputPolicy: 'agent-only' as const,
     async *run(c) {
+      const opts = c.options;
+      const interval = opts.interval;
+      const maxAttempts = opts.maxAttempts;
+      const deadline = Date.now() + opts.timeout * 1000;
+      const updateInfo = await getUpdateInfo?.({
+        polling: interval > 0,
+      });
+      const update = updateInfo
+        ? {
+            current_version: updateInfo.current,
+            latest_version: updateInfo.latest,
+            update_command: 'npm install -g @stripe/link-cli',
+          }
+        : undefined;
+
       if (!c.agent && !c.formatExplicit) {
         return new Promise((resolve) => {
           const { waitUntilExit } = render(
@@ -119,15 +135,12 @@ export function createAuthCli(
                   }
                 : {}),
               credentials_path: storage.getPath(),
+              ...(update && { update }),
             });
           });
         });
       }
 
-      const opts = c.options;
-      const interval = opts.interval;
-      const maxAttempts = opts.maxAttempts;
-      const deadline = Date.now() + opts.timeout * 1000;
       let attempts = 0;
       let previousAttemptData: string | undefined;
 
@@ -143,13 +156,6 @@ export function createAuthCli(
         }
 
         const auth = storage.getAuth();
-        const update = updateInfo
-          ? {
-              current_version: updateInfo.current,
-              latest_version: updateInfo.latest,
-              update_command: 'npm install -g @stripe/link-cli',
-            }
-          : undefined;
         if (auth) {
           yield {
             authenticated: true,

packages/cli/src/commands/spend-request/schema.ts

@@ -49,7 +49,7 @@ export const createOptions = z.object({
     .array(z.union([z.string(), z.record(z.string(), z.unknown())]))
     .default([])
     .describe(
-      'Total (repeatable, key:value format). Keys: type (required), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"',
+      'Total (repeatable, key:value format). Keys: type (required; one of: subtotal, tax, total), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"',
     ),
   requestApproval: z
     .boolean()
@@ -105,6 +105,6 @@ export const updateOptions = z.object({
     .array(z.union([z.string(), z.record(z.string(), z.unknown())]))
     .default([])
     .describe(
-      'Total (repeatable, key:value format). Keys: type (required), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"',
+      'Total (repeatable, key:value format). Keys: type (required; one of: subtotal, tax, total), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"',
     ),
 });