@stripe/link-cli 0.4.1 → 0.4.3

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:
+
+```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,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,11 @@ 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).
 
 ### 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,27 +100,52 @@ 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.
+
+Easily approve requests with the [Link app](https://link.com/download).
+
+#### 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`
 
-Users can easily approve requests with the [Link app](https://link.com/download).
+```bash
+--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)
+
+```bash
+--total "type:subtotal,display_text:Subtotal,amount:12000" \
+--total "type:total,display_text:Total,amount:12000"
+```
 
 #### 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 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.
@@ -98,8 +156,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
@@ -107,14 +164,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
 {
@@ -127,7 +184,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
 
@@ -136,44 +193,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
@@ -186,7 +236,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/dist/cli.js

@@ -3218,8 +3218,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path5) {
-      let input = path5;
+    function removeDotSegments(path6) {
+      let input = path6;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3418,8 +3418,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path5, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path5 && path5 !== "/" ? path5 : void 0;
+        const [path6, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path6 && path6 !== "/" ? path6 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -7605,12 +7605,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs4, exportName) {
+    function addFormats(ajv, list, fs5, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs4[f]);
+        ajv.addFormat(f, fs5[f]);
     }
     module.exports = exports = formatsPlugin;
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -9550,7 +9550,6 @@ var require_semver2 = __commonJS({
 
 // src/cli.tsx
 import { Cli as Cli7 } from "incur";
-import updateNotifier from "update-notifier";
 
 // ../sdk/dist/index.js
 import fs3 from "fs";
@@ -9574,12 +9573,12 @@ var disallowedKeys = /* @__PURE__ */ new Set([
   "constructor"
 ]);
 var digits = new Set("0123456789");
-function getPathSegments(path5) {
+function getPathSegments(path6) {
   const parts = [];
   let currentSegment = "";
   let currentPart = "start";
   let isIgnoring = false;
-  for (const character of path5) {
+  for (const character of path6) {
     switch (character) {
       case "\\": {
         if (currentPart === "index") {
@@ -9701,11 +9700,11 @@ function assertNotStringIndex(object, key) {
     throw new Error("Cannot use string index");
   }
 }
-function getProperty(object, path5, value) {
-  if (!isObject(object) || typeof path5 !== "string") {
+function getProperty(object, path6, value) {
+  if (!isObject(object) || typeof path6 !== "string") {
     return value === void 0 ? object : value;
   }
-  const pathArray = getPathSegments(path5);
+  const pathArray = getPathSegments(path6);
   if (pathArray.length === 0) {
     return value;
   }
@@ -9725,12 +9724,12 @@ function getProperty(object, path5, value) {
   }
   return object === void 0 ? value : object;
 }
-function setProperty(object, path5, value) {
-  if (!isObject(object) || typeof path5 !== "string") {
+function setProperty(object, path6, value) {
+  if (!isObject(object) || typeof path6 !== "string") {
     return object;
   }
   const root = object;
-  const pathArray = getPathSegments(path5);
+  const pathArray = getPathSegments(path6);
   for (let index = 0; index < pathArray.length; index++) {
     const key = pathArray[index];
     assertNotStringIndex(object, key);
@@ -9743,11 +9742,11 @@ function setProperty(object, path5, value) {
   }
   return root;
 }
-function deleteProperty(object, path5) {
-  if (!isObject(object) || typeof path5 !== "string") {
+function deleteProperty(object, path6) {
+  if (!isObject(object) || typeof path6 !== "string") {
     return false;
   }
-  const pathArray = getPathSegments(path5);
+  const pathArray = getPathSegments(path6);
   for (let index = 0; index < pathArray.length; index++) {
     const key = pathArray[index];
     assertNotStringIndex(object, key);
@@ -9761,11 +9760,11 @@ function deleteProperty(object, path5) {
     }
   }
 }
-function hasProperty(object, path5) {
-  if (!isObject(object) || typeof path5 !== "string") {
+function hasProperty(object, path6) {
+  if (!isObject(object) || typeof path6 !== "string") {
     return false;
   }
-  const pathArray = getPathSegments(path5);
+  const pathArray = getPathSegments(path6);
   if (pathArray.length === 0) {
     return false;
   }
@@ -10861,12 +10860,19 @@ function withComputedExpiry(auth) {
     expires_at: auth.expires_at ?? Date.now() + auth.expires_in * 1e3
   };
 }
+var CONFIG_FILE_MODE = 384;
 var Storage = class {
   config;
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
   getConfig() {
     if (!this.config) {
       this.config = new Conf({
         projectName: "link-cli",
+        configFileMode: CONFIG_FILE_MODE,
+        ...this.options.cwd ? { cwd: this.options.cwd } : {},
         defaults: {
           auth: null,
           pendingDeviceAuth: null
@@ -11488,7 +11494,7 @@ var AuthStatus = ({ onComplete }) => {
 
 // src/commands/auth/index.tsx
 import { jsx as jsx4 } from "react/jsx-runtime";
-function createAuthCli(authResource, updateInfo) {
+function createAuthCli(authResource, getUpdateInfo2) {
   const cli2 = Cli.create("auth", {
     description: "Authentication commands"
   });
@@ -11574,6 +11580,18 @@ function createAuthCli(authResource, updateInfo) {
     options: statusOptions,
     outputPolicy: "agent-only",
     async *run(c) {
+      const opts = c.options;
+      const interval = opts.interval;
+      const maxAttempts = opts.maxAttempts;
+      const deadline = Date.now() + opts.timeout * 1e3;
+      const updateInfo = await getUpdateInfo2?.({
+        polling: interval > 0
+      });
+      const update = updateInfo ? {
+        current_version: updateInfo.current,
+        latest_version: updateInfo.latest,
+        update_command: "npm install -g @stripe/link-cli"
+      } : void 0;
       if (!c.agent && !c.formatExplicit) {
         return new Promise((resolve) => {
           const { waitUntilExit } = render(
@@ -11588,15 +11606,12 @@ function createAuthCli(authResource, updateInfo) {
                 access_token: `${auth.access_token.substring(0, 20)}...`,
                 token_type: auth.token_type
               } : {},
-              credentials_path: storage.getPath()
+              credentials_path: storage.getPath(),
+              ...update && { update }
             });
           });
         });
       }
-      const opts = c.options;
-      const interval = opts.interval;
-      const maxAttempts = opts.maxAttempts;
-      const deadline = Date.now() + opts.timeout * 1e3;
       let attempts = 0;
       let previousAttemptData;
       while (true) {
@@ -11609,11 +11624,6 @@ function createAuthCli(authResource, updateInfo) {
           }
         }
         const auth = storage.getAuth();
-        const update = updateInfo ? {
-          current_version: updateInfo.current,
-          latest_version: updateInfo.latest,
-          update_command: "npm install -g @stripe/link-cli"
-        } : void 0;
         if (auth) {
           yield {
             authenticated: true,
@@ -12293,16 +12303,16 @@ import { useEffect as useEffect6, useRef as useRef2, useState as useState6 } fro
 
 // src/commands/mpp/decode.ts
 import { Challenge } from "mppx";
-function getString(value, path5, required = true) {
+function getString(value, path6, required = true) {
   if (value == null) {
     if (required) {
-      throw new Error(`Invalid stripe challenge request: ${path5}: missing`);
+      throw new Error(`Invalid stripe challenge request: ${path6}: missing`);
     }
     return void 0;
   }
   if (typeof value !== "string") {
     throw new Error(
-      `Invalid stripe challenge request: ${path5}: expected string, received ${typeof value}`
+      `Invalid stripe challenge request: ${path6}: expected string, received ${typeof value}`
     );
   }
   return value;
@@ -13562,6 +13572,28 @@ function createPaymentMethodsCli(createResource) {
 import { Cli as Cli6, z as z7 } from "incur";
 import { render as render6 } from "ink";
 
+// src/utils/credential-output.ts
+import fs4 from "fs/promises";
+import path5 from "path";
+async function writeCredentialFile(filePath, data, force) {
+  const resolved = path5.resolve(filePath);
+  if (!force) {
+    try {
+      await fs4.access(resolved);
+      throw new Error(
+        `OUTPUT_FILE_EXISTS: ${resolved} already exists. Use --force to overwrite.`
+      );
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  await fs4.writeFile(resolved, JSON.stringify(data, null, 2), {
+    mode: 384
+  });
+  await fs4.chmod(resolved, 384);
+  return resolved;
+}
+
 // src/utils/line-item-parser.ts
 import { z as z5 } from "zod";
 var LineItemSchema = z5.object({
@@ -13590,8 +13622,13 @@ function parseKvString(raw) {
   }
   return result;
 }
-function formatZodError(err, prefix) {
+function formatZodError(err, prefix, schema) {
+  const allowed = Object.keys(schema.shape);
   const messages = err.issues.map((issue) => {
+    if (issue.code === "unrecognized_keys") {
+      const keys = issue.keys.map((k) => `"${k}"`).join(", ");
+      return `${prefix}: unrecognized key ${keys}. Allowed keys: ${allowed.join(", ")}`;
+    }
     const key = issue.path[0]?.toString();
     return key ? `${prefix} ${key}: ${issue.message}` : `${prefix}: ${issue.message}`;
   });
@@ -13602,7 +13639,8 @@ function parseLineItemFlag(raw) {
   try {
     return LineItemSchema.parse(obj);
   } catch (err) {
-    if (err instanceof z5.ZodError) throw formatZodError(err, "Line item");
+    if (err instanceof z5.ZodError)
+      throw formatZodError(err, "Line item", LineItemSchema);
     throw err;
   }
 }
@@ -13611,7 +13649,8 @@ function parseTotalFlag(raw) {
   try {
     return TotalSchema.parse(obj);
   } catch (err) {
-    if (err instanceof z5.ZodError) throw formatZodError(err, "Total");
+    if (err instanceof z5.ZodError)
+      throw formatZodError(err, "Total", TotalSchema);
     throw err;
   }
 }
@@ -13718,11 +13757,15 @@ var CreateSpendRequest = ({
   repository,
   params,
   requestApproval = false,
+  outputFile,
+  force,
   onComplete
 }) => {
   const [status, setStatus] = useState10("creating");
   const [request, setRequest] = useState10(null);
   const [error, setError] = useState10("");
+  const [outputFilePath, setOutputFilePath] = useState10(null);
+  const [fileError, setFileError] = useState10("");
   const approvalUrl = request?.approval_url ?? "";
   const onSuccess = useCallback2(
     (result) => setRequest(result),
@@ -13758,6 +13801,18 @@ var CreateSpendRequest = ({
     };
     create();
   }, [repository, params, requestApproval, onComplete]);
+  useEffect10(() => {
+    if (status !== "success" || !outputFile || !request?.card) return;
+    const fileData = {
+      spend_request_id: request.id,
+      merchant_name: request.merchant_name,
+      merchant_url: request.merchant_url,
+      context: request.context,
+      created_at: request.created_at,
+      card: request.card
+    };
+    writeCredentialFile(outputFile, fileData, force ?? false).then((path6) => setOutputFilePath(path6)).catch((err) => setFileError(err.message));
+  }, [status, outputFile, force, request]);
   if (status === "creating") {
     return /* @__PURE__ */ jsx20(Box14, { children: /* @__PURE__ */ jsxs13(Text15, { color: "cyan", children: [
       /* @__PURE__ */ jsx20(Spinner5, { type: "dots" }),
@@ -13801,6 +13856,49 @@ var CreateSpendRequest = ({
           /* @__PURE__ */ jsx20(Text15, { bold: true, children: request.shared_payment_token.id })
         ] })
       ] }),
+      request?.card && !outputFile && /* @__PURE__ */ jsxs13(Box14, { flexDirection: "column", marginTop: 1, children: [
+        /* @__PURE__ */ jsx20(Text15, { bold: true, children: "Card Details:" }),
+        /* @__PURE__ */ jsxs13(Text15, { children: [
+          " ",
+          "Number: ",
+          /* @__PURE__ */ jsx20(Text15, { bold: true, children: request.card.number })
+        ] }),
+        /* @__PURE__ */ jsxs13(Text15, { children: [
+          " ",
+          "Brand: ",
+          /* @__PURE__ */ jsx20(Text15, { bold: true, children: request.card.brand })
+        ] }),
+        /* @__PURE__ */ jsxs13(Text15, { children: [
+          " ",
+          "Expiry:",
+          " ",
+          /* @__PURE__ */ jsxs13(Text15, { bold: true, children: [
+            String(request.card.exp_month).padStart(2, "0"),
+            "/",
+            request.card.exp_year
+          ] })
+        ] }),
+        request.card.cvc && /* @__PURE__ */ jsxs13(Text15, { children: [
+          " ",
+          "CVC: ",
+          /* @__PURE__ */ jsx20(Text15, { bold: true, children: request.card.cvc })
+        ] }),
+        request.card.valid_until && /* @__PURE__ */ jsxs13(Text15, { children: [
+          " ",
+          "Valid Until: ",
+          /* @__PURE__ */ jsx20(Text15, { bold: true, children: request.card.valid_until })
+        ] })
+      ] }),
+      request?.card && outputFile && /* @__PURE__ */ jsxs13(Box14, { flexDirection: "column", marginTop: 1, children: [
+        outputFilePath && /* @__PURE__ */ jsxs13(Text15, { color: "green", children: [
+          "Card credentials written to ",
+          /* @__PURE__ */ jsx20(Text15, { bold: true, children: outputFilePath })
+        ] }),
+        fileError && /* @__PURE__ */ jsxs13(Text15, { color: "red", children: [
+          "Failed to write card file: ",
+          fileError
+        ] })
+      ] }),
       /* @__PURE__ */ jsx20(AppDownloadQrCodes, {})
     ] });
   }
@@ -13918,12 +14016,16 @@ var RetrieveSpendRequest = ({
   id,
   timeout = 300,
   include,
+  outputFile,
+  force,
   onComplete
 }) => {
   const [phase, setPhase] = useState12("fetching");
   const [request, setRequest] = useState12(null);
   const [error, setError] = useState12("");
   const [elapsed, setElapsed] = useState12(0);
+  const [outputFilePath, setOutputFilePath] = useState12(null);
+  const [fileError, setFileError] = useState12("");
   const startTimeRef = useRef4(Date.now());
   const pollRef = useRef4(null);
   const timerRef = useRef4(null);
@@ -13934,6 +14036,18 @@ var RetrieveSpendRequest = ({
       if (timerRef.current) clearInterval(timerRef.current);
     };
   }, []);
+  useEffect12(() => {
+    if (phase !== "success" || !outputFile || !request?.card) return;
+    const fileData = {
+      spend_request_id: request.id,
+      merchant_name: request.merchant_name,
+      merchant_url: request.merchant_url,
+      context: request.context,
+      created_at: request.created_at,
+      card: request.card
+    };
+    writeCredentialFile(outputFile, fileData, force ?? false).then((path6) => setOutputFilePath(path6)).catch((err) => setFileError(err.message));
+  }, [phase, outputFile, force, request]);
   useEffect12(() => {
     const fetch2 = async () => {
       try {
@@ -14114,7 +14228,7 @@ var RetrieveSpendRequest = ({
           /* @__PURE__ */ jsx22(Text17, { bold: true, children: request.shared_payment_token.id })
         ] })
       ] }),
-      request?.card && /* @__PURE__ */ jsxs15(Box16, { flexDirection: "column", marginTop: 1, children: [
+      request?.card && !outputFile && /* @__PURE__ */ jsxs15(Box16, { flexDirection: "column", marginTop: 1, children: [
         /* @__PURE__ */ jsx22(Text17, { bold: true, children: "Card Details:" }),
         /* @__PURE__ */ jsxs15(Text17, { children: [
           " ",
@@ -14173,6 +14287,16 @@ var RetrieveSpendRequest = ({
             request.card.billing_address.country
           ] })
         ] })
+      ] }),
+      request?.card && outputFile && /* @__PURE__ */ jsxs15(Box16, { flexDirection: "column", marginTop: 1, children: [
+        outputFilePath && /* @__PURE__ */ jsxs15(Text17, { color: "green", children: [
+          "Card credentials written to ",
+          /* @__PURE__ */ jsx22(Text17, { bold: true, children: outputFilePath })
+        ] }),
+        fileError && /* @__PURE__ */ jsxs15(Text17, { color: "red", children: [
+          "Failed to write card file: ",
+          fileError
+        ] })
       ] })
     ] })
   ] });
@@ -14199,12 +14323,20 @@ var createOptions = z6.object({
   context: z6.string().min(100).describe(
     "Min 100 chars \u2014 describe the purchase and rationale; the user reads this when approving"
   ),
-  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Line item (repeatable, key:value format)"),
-  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Total (repeatable, key:value format)"),
+  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Line item (repeatable, key:value format). Keys: name (required), quantity, unit_amount, description, sku, url, image_url, product_url. Example: "name:Shoes,unit_amount:5000,quantity:2"'
+  ),
+  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    '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: z6.boolean().default(true).describe("Request approval and poll until approved/denied/expired"),
   test: z6.boolean().default(false).describe(
     "Use test mode (creates testmode credentials from test card data)"
-  )
+  ),
+  outputFile: z6.string().optional().describe(
+    "Write full card credentials to this file path; stdout shows redacted card data only"
+  ),
+  force: z6.boolean().default(false).describe("Overwrite output file if it already exists")
 });
 var retrieveOptions = z6.object({
   timeout: z6.coerce.number().default(300).describe(
@@ -14216,7 +14348,11 @@ var retrieveOptions = z6.object({
   maxAttempts: z6.coerce.number().default(0).describe(
     "Max poll attempts. 0 = unlimited. Exhaustion during active polling exits non-zero with POLLING_TIMEOUT."
   ),
-  include: z6.array(z6.string()).default([]).describe("Include extra data (repeatable, e.g. --include card)")
+  include: z6.array(z6.string()).default([]).describe("Include extra data (repeatable, e.g. --include card)"),
+  outputFile: z6.string().optional().describe(
+    "Write full card credentials to this file path; stdout shows redacted card data only"
+  ),
+  force: z6.boolean().default(false).describe("Overwrite output file if it already exists")
 });
 var updateOptions = z6.object({
   paymentMethodId: z6.string().optional().describe("Payment method ID"),
@@ -14225,8 +14361,12 @@ var updateOptions = z6.object({
   profileId: z6.string().optional().describe("Profile ID"),
   merchantId: z6.string().optional().describe("Merchant ID"),
   currency: z6.string().optional().describe("Currency code"),
-  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Line item (repeatable, key:value format)"),
-  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Total (repeatable, key:value format)")
+  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Line item (repeatable, key:value format). Keys: name (required), quantity, unit_amount, description, sku, url, image_url, product_url. Example: "name:Shoes,unit_amount:5000,quantity:2"'
+  ),
+  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    '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"'
+  )
 });
 
 // src/commands/spend-request/update.tsx
@@ -14308,6 +14448,23 @@ var UpdateSpendRequest = ({
 
 // src/commands/spend-request/index.tsx
 import { jsx as jsx24 } from "react/jsx-runtime";
+async function applyOutputFile(request, outputFile, force) {
+  if (!outputFile || !request.card) return request;
+  const fileData = {
+    spend_request_id: request.id,
+    merchant_name: request.merchant_name,
+    merchant_url: request.merchant_url,
+    context: request.context,
+    created_at: request.created_at,
+    card: request.card
+  };
+  const resolvedPath = await writeCredentialFile(outputFile, fileData, force);
+  const { card: _, ...withoutCard } = request;
+  return {
+    ...withoutCard,
+    card_output_file: resolvedPath
+  };
+}
 function createSpendRequestCli(repository) {
   const cli2 = Cli6.create("spend-request", {
     description: "Spend request management commands"
@@ -14385,6 +14542,8 @@ function createSpendRequestCli(repository) {
         request_approval: requestApproval || void 0,
         test: opts.test ? true : void 0
       };
+      const outputFile = opts.outputFile;
+      const forceOverwrite = opts.force;
       if (!c.agent && !c.formatExplicit) {
         return new Promise((resolve) => {
           let capturedResult = null;
@@ -14395,6 +14554,8 @@ function createSpendRequestCli(repository) {
                 repository,
                 params: createParams,
                 requestApproval,
+                outputFile,
+                force: forceOverwrite,
                 onComplete: (result) => {
                   capturedResult = result;
                 }
@@ -14408,7 +14569,15 @@ function createSpendRequestCli(repository) {
       }
       const created = await repository.createSpendRequest(createParams);
       if (!requestApproval) {
-        yield created;
+        try {
+          yield await applyOutputFile(created, outputFile, forceOverwrite);
+        } catch (err) {
+          const message = err.message;
+          if (message.startsWith("OUTPUT_FILE_EXISTS")) {
+            return c.error({ code: "OUTPUT_FILE_EXISTS", message });
+          }
+          return c.error({ code: "OUTPUT_FILE_WRITE_ERROR", message });
+        }
         return;
       }
       yield {
@@ -14559,6 +14728,8 @@ function createSpendRequestCli(repository) {
       const maxAttempts = opts.maxAttempts;
       const includeArr = opts.include;
       const include = includeArr?.length ? includeArr : void 0;
+      const outputFile = opts.outputFile;
+      const forceOverwrite = opts.force;
       if (!c.agent && !c.formatExplicit) {
         return new Promise((resolve) => {
           let capturedResult = null;
@@ -14570,6 +14741,8 @@ function createSpendRequestCli(repository) {
                 id,
                 timeout,
                 include,
+                outputFile,
+                force: forceOverwrite,
                 onComplete: (result) => {
                   capturedResult = result;
                 }
@@ -14599,15 +14772,20 @@ function createSpendRequestCli(repository) {
             message: `Spend request ${id} not found`
           });
         }
-        if (terminalStatuses.has(request.status)) {
-          yield request;
+        const shouldEmitFinal = terminalStatuses.has(request.status) || interval <= 0;
+        if (shouldEmitFinal) {
+          try {
+            yield await applyOutputFile(request, outputFile, forceOverwrite);
+          } catch (err) {
+            const message = err.message;
+            if (message.startsWith("OUTPUT_FILE_EXISTS")) {
+              return c.error({ code: "OUTPUT_FILE_EXISTS", message });
+            }
+            return c.error({ code: "OUTPUT_FILE_WRITE_ERROR", message });
+          }
           return;
         }
         attempts++;
-        if (interval <= 0) {
-          yield request;
-          return;
-        }
         const maxAttemptsExhausted = maxAttempts > 0 && attempts >= maxAttempts;
         const timeoutReached = Date.now() >= deadline;
         if (maxAttemptsExhausted || timeoutReached) {
@@ -14929,8 +15107,78 @@ var ResourceFactory = class {
   }
 };
 
+// src/utils/update-info.ts
+import process8 from "process";
+import updateNotifier from "update-notifier";
+var UPDATE_CACHE_TTL_MS = 60 * 60 * 1e3;
+var FAILURE_CACHE_TTL_MS = 60 * 1e3;
+var cachedUpdateInfo;
+var inflightUpdateInfo;
+function createAgentUpdateInfoProvider(packageName, cliVersion2) {
+  return async ({ polling }) => {
+    if (polling) {
+      return cachedUpdateInfo?.value;
+    }
+    const now = Date.now();
+    if (cachedUpdateInfo && cachedUpdateInfo.expiresAt > now) {
+      return cachedUpdateInfo.value;
+    }
+    if (!inflightUpdateInfo) {
+      inflightUpdateInfo = fetchLatestVersion(packageName, cliVersion2).finally(
+        () => {
+          inflightUpdateInfo = void 0;
+        }
+      );
+    }
+    return inflightUpdateInfo;
+  };
+}
+function createInteractiveUpdateInfoProvider(updateInfo) {
+  return async () => updateInfo;
+}
+function renderInteractiveUpdateNotice(updateInfo) {
+  return [
+    "",
+    `Update available for @stripe/link-cli: ${updateInfo.current} -> ${updateInfo.latest}`,
+    "Run: npm install -g @stripe/link-cli",
+    ""
+  ].join("\n");
+}
+async function fetchLatestVersion(packageName, cliVersion2) {
+  const previousDisableFlag = process8.env.NO_UPDATE_NOTIFIER;
+  try {
+    process8.env.NO_UPDATE_NOTIFIER = "1";
+    const notifier = updateNotifier({
+      pkg: {
+        name: packageName,
+        version: cliVersion2
+      }
+    });
+    const payload = await notifier.fetchInfo();
+    const latest = payload.latest?.trim();
+    const value = latest && latest.length > 0 && latest !== cliVersion2 ? { current: cliVersion2, latest } : void 0;
+    cacheUpdateInfo(value);
+    return value;
+  } catch {
+    cacheUpdateInfo(void 0, FAILURE_CACHE_TTL_MS);
+    return void 0;
+  } finally {
+    if (previousDisableFlag === void 0) {
+      process8.env.NO_UPDATE_NOTIFIER = void 0;
+    } else {
+      process8.env.NO_UPDATE_NOTIFIER = previousDisableFlag;
+    }
+  }
+}
+function cacheUpdateInfo(value, ttlMs = UPDATE_CACHE_TTL_MS) {
+  cachedUpdateInfo = {
+    expiresAt: Date.now() + ttlMs,
+    value
+  };
+}
+
 // src/cli.tsx
-var cliVersion = "0.4.1";
+var cliVersion = "0.4.3";
 var buildNumber = "1";
 var cliName = "@stripe/link-cli";
 var defaultHeaders = {
@@ -14941,14 +15189,24 @@ var verbose = process.argv.includes("--verbose");
 var factory = new ResourceFactory({ verbose, defaultHeaders });
 var authRepo = factory.createAuthResource();
 var spendRequestRepo = factory.createSpendRequestResource();
-var notifier = updateNotifier({
-  pkg: { name: cliName, version: cliVersion }
-});
 var cli = Cli7.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));
+var isAgent = process.argv.includes("--format") || process.argv.includes("--mcp");
+var agentUpdateInfoProvider = createAgentUpdateInfoProvider(
+  cliName,
+  cliVersion
+);
+var 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())
@@ -14968,10 +15226,6 @@ cli.command(
     () => factory.createPaymentMethodsResource()
   )
 );
-var isAgent = process.argv.includes("--format") || process.argv.includes("--mcp");
-if (!isAgent) {
-  notifier.notify({ defer: false });
-}
 cli.serve();
 var cli_default = cli;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripe/link-cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "bin": {
     "link-cli": "./dist/cli.js"
@@ -25,6 +25,7 @@
     "ink": "^5.2.1",
     "ink-spinner": "^5.0.0",
     "mppx": "^0.5.7",
+    "viem": "^2.47.5",
     "qrcode": "^1.5.4",
     "react": "^18.3.1",
     "update-notifier": "^7.3.1",
@@ -39,8 +40,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2",
-    "@stripe/link-sdk": "1.0.0",
-    "@stripe/link-typescript-config": "0.0.0"
+    "@stripe/link-typescript-config": "0.0.0",
+    "@stripe/link-sdk": "1.0.0"
   },
   "scripts": {
     "build": "tsup",