> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Link Cli — Agent payments via Stripe Link — cards, SPT, approvals

> Agent payments via Stripe Link — cards, SPT, approvals

Agent payments via Stripe Link — cards, SPT, approvals.

## Skill metadata

| | |
| - | - |
| Source | Optional — install with `mibyan skills install official/payments/stripe-link-cli` |
| Path | `optional-skills/payments/stripe-link-cli` |
| Version | `0.1.0` |
| Author | Teknium (teknium1), Mibyan |
| License | MIT |
| Platforms | linux, macos |
| Tags | `Payments`, `Stripe`, `Link`, `Checkout`, `MPP` |
| Related skills | [`mpp-agent`](/desktop/user-guide/skills/optional/payments/payments-mpp-agent), [`stripe-projects`](/desktop/user-guide/skills/optional/payments/payments-stripe-projects) |

## Reference: full SKILL.md

<Info>
  The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
</Info>

# Stripe Link CLI Skill

Wraps [@stripe/link-cli](https://github.com/stripe/link-cli) so Mibyan can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Mibyan cannot self-approve.

US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated `[linux, macos]`.

## When to Use

Trigger phrases:

* "buy X", "pay for X", "make a purchase", "complete checkout"
* "get me a card", "I need a payment method"
* "log in to Link", "connect my Link wallet"
* HTTP 402 response from a merchant API with `www-authenticate: ... method="stripe"`

If the user wants a paid API call (HTTP 402, no checkout form), the `card` path is wrong — use SPT via this same skill, or hand off to the `mpp-agent` skill.

## Prerequisites

* Node.js 20+ available on `PATH` (`node --version`)
* US-based (Link account requirement)

The Link account, payment method, and spend-approval app do NOT need to be set up before Mibyan attempts to pay — the CLI walks the user through them on first run:

* A Link account at [https://app.link.com](https://app.link.com) — created/linked during first `link-cli` auth
* At least one payment method — added during first run at [https://app.link.com/wallet](https://app.link.com/wallet)
* The Link mobile/web app — opened to approve the first spend request when it's made

No env vars required — auth state is stored locally by the CLI under its own config directory.

## Install

Install once, globally:

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

Or invoke ad-hoc via `npx @stripe/link-cli`. The skill below uses the installed `link-cli` form.

## How to Run

All commands run through the `terminal` tool. The CLI auto-detects non-TTY callers and emits compact `toon` output by default — fine for the model. Pass `--format json` if a step needs structured fields.

Discover commands: `link-cli --llms-full`.
Get a command's schema before invoking: `link-cli <command> --schema`.

## Procedure

### 1. Check / establish auth

```
link-cli auth status
```

If not authenticated, log in with a clear client name (this label shows in the user's Link app):

```
link-cli auth login --client-name "Mibyan" --interval 5 --timeout 300
```

The `--interval`/`--timeout` form polls inline so the agent doesn't need to manage a `_next` step. Print the verification URL + phrase to the user and wait for the CLI to return.

**Do not proceed past this step until `auth status` confirms login.**

### 2. Evaluate the merchant before creating a spend request

Decide the credential type:

| Merchant surface | `--credential-type` |
| - | - |
| Standard web checkout form / Stripe Elements | `card` (default) |
| Returns HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` |
| Returns HTTP 402 without `method="stripe"` | unsupported — stop |

For 402 responses, do NOT decode the challenge manually. Pass the raw header:

```
link-cli mpp decode --challenge '<full WWW-Authenticate header>'
```

This validates the challenge and extracts the network ID + decoded request body.

### 3. List payment methods + shipping

```
link-cli payment-methods list
link-cli shipping-address list
```

Use the first entry unless the user specifies otherwise. The `id` from `payment-methods list` is the `--payment-method-id` in the next step.

### 4. Create the spend request

Confirm the final total with the user before issuing this command. Amounts are in cents.

```
link-cli spend-request create \
  --payment-method-id <pm_id> \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --context "<one sentence: what is being purchased and why>" \
  --amount <cents> \
  --line-item "name:<item>,unit_amount:<cents>,quantity:1" \
  --total "type:total,display_text:Total,amount:<cents>" \
  --request-approval
```

For MPP merchants add `--credential-type shared_payment_token`.

`--request-approval` pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout.

### 5. Retrieve the credential — SECURELY

**Do not print card details to stdout.** Use `--output-file` so the PAN never enters the agent's transcript or logs:

```
link-cli spend-request retrieve <lsrq_id> \
  --include card \
  --output-file ~/.mibyan/cache/scratch/link-card.json \
  --format json
```

The file is written with `0600` perms; stdout shows only redacted fields (brand, last4, expiry) plus a `card_output_file` path.

### 6. Use the credential

* For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never `read_file` or `cat` the card file into the agent's reasoning context.
* For MPP merchants:

  ```
  link-cli mpp pay <merchant-url> \
    --spend-request-id <lsrq_id> \
    --method POST \
    --data '<json body>'
  ```

### 7. Clean up

Delete the card file as soon as the purchase is done:

```
rm -f ~/.mibyan/cache/scratch/link-card.json
```

## Optional: run as an MCP server instead

`@stripe/link-cli --mcp` exposes the same commands as MCP tools over stdio. To register it with Mibyan' native MCP:

```
mibyan mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"
```

Then `mibyan mcp list` should show `stripe-link`. The same approval rules apply — MCP doesn't bypass the Link app approval step.

## Pitfalls

* **US-only.** Outside the US, `auth login` will fail. Tell the user, don't keep retrying.
* **Card PAN must never enter agent context.** Use `--output-file` every time. If you've already retrieved without it, immediately `link-cli auth logout` is not enough — the card is one-time-use but rotate hygiene matters.
* **`--request-approval` blocks until the user acts.** If the user is asleep, the CLI will hit its timeout. Set expectations.
* **Multi-step `_next` commands.** Some commands return `_next.command` that must be executed to continue. When in doubt, prefer the inline-polling flags (`--interval`/`--timeout`).
* **Output format defaults to `toon`** in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass `--format json`.
* **Don't default to `card`.** The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed.

## Verification

```
link-cli --version && link-cli auth status
```

Exit code 0 means installed and logged in.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.