link-cli: giving an agent a spending credential instead of your card number

Agents that spend money without touching a real card

The problem link-cli addresses is specific: an agent needs to buy something on a user's behalf, and the usual answer is to hand it a card number, which means the agent, its vendor and its logs all handle credentials the user never intended to share. The Link CLI takes a different route. It pulls a credential out of a Link wallet for a one time purchase or for recurring payments, and the real card details stay at Link. The project description states the promise plainly, letting agents spend on your behalf with payment credentials that are never exposed, where every purchase is approved.

The intended user is a developer building an agent, and the README points consumers of that product to a separate section for integrating the Link CLI into their own agent. There is a second audience: the operator of the agent, who holds a Link account and decides how much the agent may spend and when it needs a human.

Two constraints bound everything else in the project. A Link account is required, and the credential feature is currently available only to US and Canadian Link accounts. For everyone else the tool exists but cannot yet be used, which is worth checking before designing an agent workflow around it.

Three credential types with different acceptance

The CLI can produce one of three credentials, and choosing wrong is the most common way to waste an afternoon, because each one is accepted in a different place.

A virtual card, described as a PAN, is for a standard web checkout form. The README is explicit that the issued card works anywhere and is not restricted to Link enabled sellers or sellers that use Stripe. That makes it the most portable option, and also the least protective, since it is a card number handed to a checkout form.

A Link Pay Token, or LPT, is for supported Stripe payment surfaces. Stripe checkout pages use WebMCP so an agent can complete a checkout, which means the purchase flow stays on Stripe rather than being replayed against an arbitrary form.

A Shared Payment Token, or SPT, is for the case where the seller accepts programmatic payments through Machine Payment Protocols, with the concept documented by Stripe and MPP. This is the credential aimed at agent to agent commerce rather than at a browser checkout.

The three options are not variations on a theme. One is a card, one is a Stripe surface token, one is a programmatic protocol credential, and the right choice depends on who the seller is.

Installing the CLI and approving the first connection

The CLI is published to npm under the `@stripe/link-cli` scope, so installation is a global npm install, or a direct `npx` invocation without installing anything:

npm i -g @stripe/link-cli

npx @stripe/link-cli

A Link account is required before anything else works. The README points to an existing account or to creating one online at `app.link.com`, and the login command starts an approval flow:

link-cli auth login

You receive a verification URL and a short phrase. Visiting the URL, logging in to the Link account and entering the phrase approves the connection. That pairing of a URL and a phrase is a deliberate design choice: it proves you are at the browser approving this machine, without the CLI ever asking for your Link password.

After that, the onboarding flow wires the pieces together for you, and it is the fastest way to see the whole picture in one run.

link-cli onboard

Agents can also install the packaged skill, which gives a coding agent the command reference in its own format:

npx skills add stripe/link-cli

Walking the spend request path one lookup at a time

The command surface is a set of resource style subcommands, and reading them in order shows the whole data flow. Identity and limits come first:

link-cli user-info retrieve --format json

Beyond identity fields, that response can include the user's address, balance eligibility, spend limits and verification requirements. The address and `eligible_for_balance` fields are omitted when that enrichment is unavailable, and both are null and false when the user has no Person record. Finite spend limit values are in cents, because the response carries no currency field, and a null limit or remaining amount means unlimited.

Next come the payment methods, which are the cards and bank accounts saved to the Link account:

link-cli payment-methods list

The `id` field is what you pass as `payment_method_id` later. A list can also include a Link balance payment method with its available balance when that amount is available. Individual methods can be fetched or renamed by ID, and passing an empty string to `--nickname` clears the name.

What the agent may spend without asking a human is a separate question, and it has its own command:

link-cli approval-policy retrieve --format json

Each rule carries an action, a per purchase limit and optionally an ordered list of allowed payment method IDs. The API returns an error when no approval policy has been configured, which is the failure mode to expect for an app that has never been granted spend authority.

The MCP server mode is where the security trade-off lives

Link CLI can run as a local MCP server, which is the integration path for coding agents that speak MCP rather than shelling out to a binary. The client configuration is a single entry:

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

There is also a `serve` mode that exposes the CLI as an HTTP MCP endpoint:

link-cli serve            # binds 127.0.0.1:54321 (loopback only)
link-cli serve --port 8080
link-cli serve --host 0.0.0.0   # expose beyond localhost (see warning below)

The README states the risk in plain terms: anyone who can reach the port can use the CLI's authenticated Link session, so `--host` should only be overridden on a trusted, isolated network, and doing so prints a warning. The default bind address is `127.0.0.1`, so only the local host can reach it.

The route handling is also specified. The server answers `POST /mcp`, serves skill discovery at `/.well-known/skills/index.json` and `/.well-known/skills/{skill-name}/SKILL.md`, supports `OPTIONS` preflight, returns `404` for other paths, `405` for unsupported methods and `400` for malformed or ambiguous request paths. Those status codes are worth noting if you are writing a health check or a proxy in front of it.

Output formats built for a model, not a human

When the CLI is called from an agent rather than a terminal, it changes its output format. By default in a non TTY context all commands use `toon`, described in the README as a compact, LLM friendly text format. Every command also accepts `--format [format]` for structured output, with `json`, `yaml`, `md` and `jsonl` available.

Two discovery commands exist for that same audience:

link-cli --llms-full

lists the available commands, and a command's full schema can be fetched with `--schema`:

link-cli spend-request create --schema

This is a small design choice with a large effect on how an agent uses the tool. Rather than parsing help text, the agent can fetch a machine readable schema for the exact command it intends to run, and it can choose the output encoding that suits the surrounding pipeline. `jsonl` in particular suits a streaming consumer that wants one record per line.

The repository ships the same content as an agent skill through `skills/` and plugin directories for `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/`, and the root `package.json` includes a `sync-skill-version` script that keeps the published skill version in step with the CLI.

Monorepo layout, release cadence and the cost of upgrading

The repository is a pnpm workspace driven by Turborepo, with `packages/` holding the CLI, the SDK and the integrations, `turbo.json` at the root and a `pnpm-workspace.yaml`. The root `package.json` declares `[email protected]` as the package manager and requires Node `>=24`, which is a real constraint for CI images and developer machines that still run an older LTS.

The test script shows the shape of the codebase. Alongside the JavaScript suite it runs a Go test suite and a Python test suite:

turbo run test && pnpm run test:go && pnpm run test:python

with `go -C packages/sdk-go test ./...` and a `uv` driven `pytest` run in `packages/sdk-python`, linted and type checked with `ruff` and `ty`. Biome handles linting and formatting, and Changesets handles versioning, which is why releases are published per package rather than as one artifact.

Three packages were released on 2026-10-19: `@stripe/[email protected]`, `@stripe/[email protected]` and `@stripe/[email protected]`. The last push was on 2026-10-19 as well, so the project is moving quickly, and the version numbers being independent means a consumer of the SDK can upgrade without taking a new CLI.

The licence is MIT, which covers the code in this repository. It says nothing about the terms of Link itself, the Stripe API, the payment rails, or the merchants that accept these credentials, and those are the terms that actually govern a payment deployment.

Editorial conclusion

Adopt link-cli when you are building an agent that must spend money on a user's behalf and you want the Link approval flow, the spend limit controls and the MCP integration in one tool, and accept that only US and Canadian Link accounts are supported today. Do not adopt it as a general payment integration, since the credential types are narrow and the CLI expects Node 24 or newer. Verify first which of the three credential types your seller accepts, then confirm the approval policy your app is granted with `link-cli approval-policy retrieve --format json` before letting an agent create spend requests.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stripe/link-cli on GitHub