CLI reference

Link CLI provides ready-made commands for connecting a Link account, creating customer-approved spend requests, retrieving scoped payment credentials, and completing machine payments.

Usage

Run Link CLI without installing it globally:

npx @stripe/link-cli --help

Global install

Install Link CLI when a guide expects the link-cli command to be available:

npm install -g @stripe/link-cli
link-cli --help

Commands and options

List every command or inspect the help and schema for one command:

link-cli --llms-full
link-cli spend-request create --help
link-cli spend-request create --schema

Authentication

Start login, wait for authentication, inspect the session, or log out. These commands show separate operations:

link-cli auth login --client-name "Claude Code"
link-cli auth login --client-name "Claude Code" --interval 5 --timeout 300
link-cli auth status
link-cli auth logout

auth login returns a verification URL and short phrase for the customer to approve. auth upgrade merges new scopes with the current grant and requests approval for the combined set. The current session remains valid until the replacement is approved.

The default scopes are userinfo:read and payment_methods.agentic. To read financial data, also request source actions at login, or add them later with auth upgrade:

link-cli auth login --client-name "My Agent" \
  --scope "userinfo:read" \
  --source-actions read_link_transactions \
  --source-actions read_external_transactions \
  --source-actions read_balances \
  --source-actions read_source_details

See Financial insights for the full flow. auth status prints the granted scopes and the exact credential-file path. Link CLI stores that file with 0600 permissions, refreshes an access token one minute before expiry, and persists rotated tokens. auth logout makes a best-effort attempt to revoke the refresh token, then deletes the local credential file.

All authenticated commands accept --auth <path> to use a separate credential file.

Spend requests

Use spend-request create to describe the seller, amount, purchase context, and requested credential. Add --test while developing to receive test credentials. If you omit --currency, Link uses the consumer’s default spend-request currency; see Currency. The example that follows creates a live request. Link requests approval by default and notifies the customer. Pass --no-request-approval to defer it. An interactive terminal polls internally. Non-interactive or structured output returns immediately with an _next retrieve command. Use --idempotency-key (1–255 bytes, no personal data) so a retried create returns the original response.

link-cli spend-request create \
  --merchant-name "Acme" \
  --merchant-url "https://acme.example" \
  --context "The user asked the agent to purchase the selected item from Acme for the displayed total, including shipping." \
  --amount 2599 \
  --currency usd

Retrieve, update, request approval for, or cancel an existing request:

link-cli spend-request retrieve lsrq_001
link-cli spend-request update lsrq_001 --amount 2999
link-cli spend-request request-approval lsrq_001
link-cli spend-request cancel lsrq_001

See Spend requests for lifecycle and credential details. A command that exits successfully hasn’t necessarily been approved or paid, so inspect the returned status. If it is requires_action, branch on resolution; see Handle required actions, including partner verification.

Line items and totals

--line-item and --total are repeatable and accept comma-separated key:value fields.

link-cli spend-request create ... \
  --line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners" \
  --total "type:subtotal,display_text:Subtotal,amount:12000" \
  --total "type:total,display_text:Total,amount:12000"

A line item requires name. Optional keys are quantity, unit_amount, description, sku, url, image_url, and product_url. A total requires type, display_text, and amount. Total types are subtotal, tax, total, items_base_amount, items_discount, discount, fulfillment, shipping, fee, gift_wrap, tip, and store_credit.

Recurring payments

Add --recurring-interval to create a repeating spending limit. --recurring-interval-count is optional.

link-cli spend-request create \
  --merchant-name "Example Pro" \
  --merchant-url "https://example.com/subscribe" \
  --context "Monthly access to Example Pro requested by the user, with a spending limit of 20 USD per month including all taxes." \
  --amount 2000 \
  --currency usd \
  --recurring-interval month

--amount is the limit for each period in the currency’s minor units, not a lifetime budget. Omit both flags for a one-time request. The flags are create-only, so spend-request update can’t change them. spend-request cancel revokes the credential but doesn’t cancel the merchant’s subscription; cancel that with the merchant too. See Recurring payments.

Completion callbacks

Use --completion-callback-url and --nonce together on spend-request create to return the customer to your application:

link-cli spend-request create ... \
  --completion-callback-url "https://agent.example.com/link/callback" \
  --nonce "$NONCE"

Supply both or neither. The URL must be valid and at most 2,048 characters, and the nonce must be nonblank and at most 512 JavaScript/UTF-16 code units. The API enforces HTTPS and URL security rules in live mode. Save the nonce unchanged and verify an exact match on callback. A callback doesn’t prove approval or payment, so retrieve the request and inspect its status. Use the returned approval_url and action_url values as-is. See Return the customer to your app.

Metadata

Attach up to 50 string keys with repeatable --metadata flags:

link-cli spend-request create ... \
  --metadata "order_id:ord_123" \
  --metadata "team:growth"

Keys can contain at most 40 characters and values at most 500 characters.

Machine payments

Handle a complete HTTP 402 flow, or inspect a challenge separately:

link-cli mpp decode --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
link-cli mpp pay https://merchant.example/paid \
  --method POST \
  --data '{"amount":100}' \
  --context "Purchasing the item selected by the user from the MPP seller. The seller returned an HTTP 402 challenge for this exact amount."

Without --spend-request-id, mpp pay probes the URL, parses the challenge, creates and requests approval for a one-time spend request, and completes payment after approval. Pass --test to use a test credential. Without it, customer approval authorizes a live payment.

See Machine payments for the complete procedure.

Update a payment method

After you authenticate, you can update a payment method’s nickname or set it as the wallet default. Run the command with --help to see the available options:

link-cli payment-methods update --help

Setting a default changes the customer’s wallet-level default, not just the payment method for one spend request, so make the change only when the customer asks for it. To choose a method for a single purchase, pass --payment-method-id to spend-request create instead.

Shipping addresses

After you authenticate, you can list the customer’s saved shipping addresses as JSON:

link-cli shipping-address list --format json

Each record has these properties:

The address properties are name, line_1, line_2, locality, dependent_locality, administrative_area, postal_code, sorting_code, and country_code. Each can be null. Handle a null or incomplete address before using its details.

Use the address with is_default: true unless the customer selects another.

Identity

Answer a service’s attestation or claims challenge. These commands are in beta, require Link CLI v0.27.0 or later, and aren’t available as MCP tools:

link-cli identity attestations request --count 10
link-cli identity attestations pop --format json
link-cli identity credentials request
link-cli identity credentials present --aud https://shop.example --nonce "$NONCE" --claim email --format json
link-cli identity attestations list --format json
link-cli identity credentials list --format json

Only the request commands need Link authentication, and their output contains file paths and metadata, never tokens or claim values. Send authorization from pop as the Authorization header, and presentation from present as the Identity-Presentation header. See Prove and verify identity.

Structured output

Every command accepts --format. In a non-interactive agent environment, Link CLI defaults to toon. Other formats are json, yaml, md, and jsonl.

link-cli payment-methods list --format json

When retrieving full card details, use --output-file to keep the credential out of stdout and agent transcripts:

link-cli spend-request retrieve lsrq_001 \
  --include card \
  --output-file "$(mktemp -d)/link-card.json" \
  --format json

When spend-request retrieve polls, inspect the returned status. Exit code zero means polling completed, not that the customer approved the request or the purchase succeeded. See Poll for approval for status handling, required actions, and timeouts.

Agent integration

Add Link CLI to a Model Context Protocol (MCP) client without a global install:

{
  "mcpServers": {
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}

See Agent integration for skills, schemas, MCP over HTTP, polling, and credential handling.

Environment variables

Use these variables to configure authentication, endpoints, and diagnostics:

Limits

These limits apply to spend requests and their payment credentials:

Eligible virtual-card credentials can expire without a first authorization within 48 hours of first retrieval, or sooner if the request expires. This deadline doesn’t apply to all cards or to returned SPTs.

Test mode

--test returns test credentials and never charges the underlying payment method. Only some commands accept it:

The financial-insights commands have no test mode. Use live accounts.

Demos

Demo flows always run in test mode and never create real charges.

link-cli demo
link-cli demo --only-card
link-cli demo --only-spt