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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# agent-cards init

> Add the Commerce SDK to your project, and have Agentcard's agent build it in.

Run `init` in your app's folder. The CLI asks four questions, installs `@agent-cards/commerce-sdk` with your package manager, and then Agentcard's agent builds the buy tool into your code while you watch.

```bash theme={null}
agent-cards init --help
```

```text theme={null}
Usage: agent-cards init [options]

Set up the Agentcard Commerce SDK in this project, and have Agentcard's agent
build it in

Options:
  --product <product>      Non-interactive: commerce-sdk (vault and issuing are
                           coming soon)
  --mode <mode>            production (default) or sandbox: the credentials put
                           in your env file
  --categories <list>      Non-interactive: all, or a comma list of shopping,
                           food, groceries, flights, hotels, restaurants,
                           classes, tickets
  --implementation <type>  Non-interactive: tool (api is coming soon)
  --wallet <list>          Non-interactive: vault, link, or both as a comma
                           list in the order shoppers see them, such as
                           vault,link (shop-pay is coming soon)
  --yes                    Yes to installing the SDK and to starting
                           Agentcard's agent, without asking
  --skip-install           Set up without installing the SDK
  --print                  Print the instructions for your own coding agent
                           instead of running Agentcard's (the default without
                           a terminal)
  -h, --help               display help for command
```

## Answer the four questions

```bash theme={null}
cd my-agent-app
agent-cards init
```

Each question lists every option, as radio buttons, or as checkboxes for the stores and the wallets. Options that aren't ready yet are listed too, dimmed with "coming soon", and the cursor skips them:

```text theme={null}
  Agentcard  init

  Four questions, then the SDK is installed and Agentcard's agent builds it in.

  ? Which Agentcard product are you adding?  1/4
    ● Commerce SDK  one tool that buys from stores for your users
    ○ Vault         coming soon
    ○ Issuing       coming soon
    ↑↓ to move, enter to choose
```

The CLI asks:

1. Which Agentcard product you're adding: `Commerce SDK`, first in the list. `Vault` and `Issuing` show under it but are coming soon, so you can't pick them yet.

Then it says how many stores the Commerce SDK adds, and asks:

2. Which stores your agent buys from: `All stores`, or the categories you check with the space bar. The categories are online shopping, food delivery, groceries, flights, hotels, restaurant reservations, fitness classes and event tickets.
3. How your agent uses it: `Tool`, one buy tool your agent calls. `API` is coming soon.
4. Which wallets pay, in the order shoppers see them: check `Agentcard Vault`, `Stripe Link`, or both with the space bar. The order you check them in is the order your users see them. With the Vault, your users save their card once and approve each purchase with their passkey. With Stripe Link, your users approve each store's payment in their own Stripe Link wallet, which pays at store checkouts across the web and for the hotels, rental cars and flights they book. Each answer says which wallets can pay its carts. `Shop Pay` shows in the list but is coming soon.

With Stripe Link checked, Agentcard's agent also mounts the Link sign-in routes and reads your Link app's keys, `LINK_CLIENT_ID`, `LINK_CLIENT_SECRET` and `LINK_PUBLISHABLE_KEY`, from the environment on your server only, and lists them in `.env.example`. Put their values in your env file yourself: the CLI writes only Agentcard's credentials there. Register the Link app with Stripe first, as [Connecting a shopper's Stripe Link wallet](https://docs.agentcard.com/commerce-sdk/guides/connecting-a-link-wallet.md) describes. Without a terminal, pass the wallets in order, such as `--wallet vault,link`.

Then it shows your choices:

```text theme={null}
  ✓ Which stores should your agent buy from?  Online shopping, Flights
  ✓ How will your agent use it?  Tool
  ✓ Which wallets pay, in the order shoppers see them?  Agentcard Vault

  Your setup
  Product          Commerce SDK
  Stores           Online shopping, Flights
  Implementation   Tool
  Wallet           Agentcard Vault
```

## Approve once

The CLI lists every step that changes something, then asks one question, with yes as the answer when you press Enter:

```text theme={null}
  Next
  1. Install @agent-cards/commerce-sdk  npm install @agent-cards/commerce-sdk
  2. Sign in to Agentcard in your browser, or create your account
  3. Name your company, if it's your first time
  4. Put your production credentials in .env, kept out of git
  5. Let Agentcard's agent build it into this project
  6. Add credits or a payment method in your browser, so your agent can buy for real

  ? Go ahead?  ● Yes  ○ No
```

The sign-in steps show only when you're not signed in. Signed in to an account with no company yet, the list says `Name your company` instead. If your git repository has uncommitted changes, the CLI says so above the question: commit first, so you can review the agent's changes apart from yours. A no installs and changes nothing.

You can run `init` from any folder inside your app, such as `src/`: the CLI works on the nearest folder above it with a `package.json`, and Start it begins with the `cd` back into the app.

## Install the SDK

A spinner shows while the SDK installs, then `✓ Installed @agent-cards/commerce-sdk`. The package manager's own output appears only when the install fails. The CLI uses the package manager your lockfile names: `pnpm add` with `pnpm-lock.yaml`, `yarn add` with `yarn.lock`, `bun add` with `bun.lock` or `bun.lockb`, and `npm install` otherwise. In a monorepo package it reads the workspace root's lockfile. A folder with no `package.json` installs nothing, and the CLI tells you to run `init` from your app's folder. `--skip-install` sets everything up without installing.

## Let Agentcard's agent build it in

After the install, Agentcard's agent reads your code, wires in the buy tool, runs your typecheck, and ends with a short report. The agent runs on Agentcard's account, so you need no model key of your own. Before it starts:

* You need to be signed in. If you are not, the CLI opens app.agentcard.sh in your browser. Sign in, or sign up with a new email: a sign-in that `init` starts creates your Agentcard account. Then the browser hands you back to the terminal.
* Your account needs a company. A new account names it right there, with your work email's domain offered as the name, and the CLI creates the company with you as its owner:

```text theme={null}
  Your account has no company yet. Name it, and Agentcard sets it up.
  ✓ What's your company called?  Acme
  ✓ Created Acme. You're its owner.
  ✓ Put Acme's production credentials in .env
  ✓ Added .env to .gitignore, so it's never committed
```

An account with several companies picks one from a list. You never need the dashboard for any of it.

* The CLI puts your company's production client ID and secret in your app's env file, and creates them when your company has none yet (that needs an owner or admin, and an active subscription). `--mode sandbox` puts the sandbox ones there instead. The file is `.env.local` for Next.js, `.env` otherwise. The CLI adds that file to `.gitignore` so the secret is never committed. Agentcard credentials already in the file, from an earlier run or another company, are replaced; the rest of the file stays. An env file that git already tracks is left alone.
* With production credentials the agent checks the buy tool without buying anything. The agent stops at the add-a-card link, since adding a card and approving a payment are a real person's own steps.

While the agent works, each step shows as one dim line, with the agent's own messages in between and a spinner while it thinks:

```text theme={null}
  ✓ Put Acme's production credentials in .env
  ✓ Added .env to .gitignore, so it's never committed

  Agentcard's agent is building it in  Ctrl+C to stop
  Run init_8bb2142a-4e83-4e84-ad76-3277955ce10f

  · Read    package.json
  · Read    node_modules/@agent-cards/commerce-sdk/README.md

  Reading the agent first, then wiring in the buy tool.

  · Edited  src/agent.ts
  · Ran     npm run typecheck
    failed, the agent looks at why
  · Edited  src/agent.ts
  · Ran     npm run typecheck
  ⠧ Thinking
```

The agent ends with a short report in bullets: what it built, each check it ran and whether it passed, and up to three things to check by hand. Then the CLI lists every file that changed and how to review them, has your company set up live purchases, and last, shows the command that starts your app:

```text theme={null}
  - Wired the buy tool into the terminal chat in src/index.ts.
  - Typecheck: passed.
  - Walkthrough: passed.
  - Check by hand: continue to checkout and stop at the add-a-card link.

  ✓ Agentcard's agent finished  71s · 17 turns · 489,838 tokens in · 7,812 out

  Files changed
    .env.example
    .gitignore
    package-lock.json
    package.json
    src/agent.ts
    src/index.ts

  › Review it with git diff, and git status for new files

  Make real purchases
    Your agent can't buy for real until you add credits to Acme's balance or connect a payment method.
  › Opening Acme's balance in your browser
    https://app.agentcard.sh/org/org_3f2a9c1e7b6d4a5e8f0c2d1b/agents/balance

  ✓ Live purchases are on for Acme

  Start it
    node --env-file=.env --import tsx src/index.ts
```

The agent never commits, pushes or deploys. When it names no start command, the CLI shows your project's `dev` or `start` script instead.

## Turn on live purchases

Agentcard charges a fee on every live purchase, so production credentials buy for real only once your company can pay it: add credits to its balance, or connect a payment method to pay as you go. After the agent finishes, the CLI opens Commerce SDK → Balance in your dashboard, where you do either, and waits. When your company can pay, the CLI says `✓ Live purchases are on` and shows the command that starts your app.

Press Enter to skip and fund later: [`agent-cards fund`](https://docs.agentcard.com/tools/cli/fund) opens the same page any time, and if it isn't done in 30 minutes, Agentcard emails you the link. If your company can already pay, or with `--mode sandbox`, the CLI skips this step.

## Know what the agent can touch

The agent works in your project folder: it reads, edits and searches files there, and runs commands such as installs, typechecks and tests. The CLI refuses file-tool requests for paths outside the folder and env files other than `.env.example`. The CLI also refuses commands that print an env file or the environment. Your app reads the credentials from the environment, so the agent never needs their values.

The CLI checks the agent's requests, but does not sandbox its commands. The agent's commands run as you, with your permissions, so a command or a script the agent writes and runs can reach files outside the folder. Commit your work before you start, and review every change with `git diff`.

A run stops after 30 minutes, or sooner when it reaches its limit for one run. Your account also has a daily limit for the agent. When you reach it, the CLI says so, and the limit resets within 24 hours:

```text theme={null}
  ✗ You've reached today's limit for Agentcard's agent. The limit resets within 24 hours. Until then, `agent-cards init --print` gives you the instructions for your own coding agent.
```

Press Ctrl+C to stop the agent. What it changed so far stays in place, and the CLI lists those files:

```text theme={null}
  ! Stopped. What the agent changed so far stays in place.
```

Ctrl+C at a question before the approval cancels `init` before anything changes. If you cancel a later question, such as your company's name, the CLI leaves the steps already done in place, such as copying the example app and installing the SDK:

```text theme={null}
  ✗ Which stores should your agent buy from?

  Cancelled.
```

## Start from an empty folder

Run `init` in an empty folder and the CLI first copies Agentcard's example app there: a terminal chat on the Vercel AI SDK that buys from real stores with the buy tool. Everything after that is the same as in any project: the four questions, one approval, the install, your credentials, and Agentcard's agent fitting the app to your answers.

```bash theme={null}
mkdir my-shopping-agent && cd my-shopping-agent
agent-cards init
```

An empty folder has no `package.json` and nothing in it but dot files, such as `.git` or `.gitignore`. A folder with any other file in it is treated as your project. Run from a folder inside an app, such as `src/`, `init` works on the app as usual; an empty folder inside an app still gets the example app, since that is where you asked for a new one. The CLI says so first, before any question.

The approval lists copying the app as the first step:

```text theme={null}
  Next
  1. Create Agentcard's example app here, a terminal chat that buys
  2. Install @agent-cards/commerce-sdk  npm install @agent-cards/commerce-sdk
  3. Sign in to Agentcard in your browser, or create your account
  4. Name your company, if it's your first time
  5. Put your production credentials in .env, kept out of git
  6. Let Agentcard's agent build it into this project
```

After the yes, the CLI downloads the app from GitHub, then carries on as in any project. A file already in the folder is never overwritten. The agent is told the app started from the example, so it keeps it working and changes it to fit your answers, such as the stores you picked. The last lines say how to start the app, and name the one value only you have, your Anthropic key.

Without a terminal, the same flags as any project apply, and `--yes` copies the app, installs and prints the instructions. `--print` in an empty folder prints the instructions for your own coding agent and creates nothing.

## Use your own coding agent

`--print` skips Agentcard's agent and prints the instructions for your own, such as Claude Code, Cursor or Codex:

```bash theme={null}
agent-cards init --print > agentcard-instructions.md
```

The instructions start with your setup, then the Commerce SDK guide that [`agent-cards guide commerce-sdk`](https://docs.agentcard.com/tools/cli/guide) prints:

```text theme={null}
## This project's setup

`agent-cards init` set this project up with these choices. Build to them:

- Stores: all of them (5000+), every kind of purchase the buy tool makes.
- Implementation: Tool. The agent calls the buy tool from `buyTool`, one tool per shopper.
- Wallet: Agentcard Vault. Shoppers save their card once in the Vault and approve each purchase with their passkey.
- Package: `@agent-cards/commerce-sdk` is installed.
- Production credentials: run `agent-cards credentials --mode production --yes`. ...
```

## Run it without a terminal

A coding agent or a CI job answers every question with a flag:

```bash theme={null}
agent-cards init --categories shopping,food --implementation tool --wallet vault --yes
```

Without a terminal, `init` installs the SDK and prints the instructions on stdout, the same as `--print`. Its other notes go to stderr, so `> file` captures the instructions alone. A missing flag stops it before anything runs:

```text theme={null}
Error: init asks its questions in a terminal. Without one, answer them with flags:
  --categories all (or a comma list, such as shopping,food)
  --implementation tool
  --wallet vault, link, or both in order (vault,link)
  --yes to install, or --skip-install
Example: agent-cards init --categories all --implementation tool --wallet vault,link --yes
```

Without a terminal the product is the Commerce SDK, so `--product` is optional. `--product vault` and `--product issuing` are refused until they set up here:

```text theme={null}
Error: Vault setup is coming soon. Use --product commerce-sdk for now.
```

`--implementation api` is refused until the API arrives:

```text theme={null}
Error: The API implementation is coming soon. Use --implementation tool for now.
```

In a terminal, a flag answers its own question and the CLI asks the rest. `--yes` is the one approval, so nothing more is asked. With `--print` in a terminal, the install is the only change, so the CLI asks before it installs.


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