agent-cards init

Run init in your app’s folder. The CLI asks three 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.

agent-cards init --help

Usage: agent-cards init [options]

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

Options:
  --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 <wallet>        Non-interactive: vault
  --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 three questions

cd my-agent-app
agent-cards init

The CLI first says how many stores the Commerce SDK adds, then asks:

Which stores your agent buys from: All stores, or the categories you check. The categories are online shopping, food delivery, groceries, flights, hotels, restaurant reservations, fitness classes and event tickets.
How your agent uses it: Tool, one buy tool your agent calls. The CLI shows a short example of the code above the question. API is coming soon.
Which wallet pays: Agentcard Vault. Your users save their card once and approve each purchase with their passkey. More wallets are coming soon.

Then it shows your choices:

  Your setup
  Stores          All stores (18+)
  Implementation  Tool
  Wallet          Agentcard Vault

Install the SDK

The CLI asks before it installs, with yes as the answer when you press Enter:

? Install the SDK now? (npm install @agent-cards/commerce-sdk) (Y/n)

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, the CLI asks once more:

? Let Agentcard's agent build it into this project? (Y/n)

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 offers to sign you in right there and then carries on.
If your git repository has uncommitted changes, the CLI says so and asks whether to go on, with no as the answer when you press Enter. Commit or stash first, so the agent’s changes are easy to review and undo.
The CLI puts your company’s sandbox client ID and secret in your app’s env file: .env.local for Next.js, .env otherwise. It adds that file to .gitignore so the secret is never committed. An env file that already has AGENTCARD_CLIENT_ID is kept as it is, and an env file that git already tracks is left alone.

While the agent works, each step shows as one line, with the agent’s own messages in between:

  Put Acme's sandbox credentials in .env.
  Added .env to .gitignore, so it's never committed.

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

  · Read node_modules/@agent-cards/commerce-sdk/README.md
  · Read node_modules/@agent-cards/commerce-sdk/examples/anthropic.mjs
  · Edited src/agent.ts
  · Ran npm run typecheck

  Typecheck passes. Running the walkthrough in the sandbox.

When it finishes, the CLI lists every file that changed and how to review them:

  ✔ 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.

The agent never commits, pushes or deploys. Read its report for the checks it ran and the ones to do by hand, such as adding a card in the Vault with the sandbox code 111111.

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:

  You've reached today's limit for Agentcard's agent. It 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:

  Stopped. What the agent changed so far stays in place.

Use your own coding agent

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

agent-cards init --print > agentcard-instructions.md

The instructions start with your setup, then the Commerce SDK guide that agent-cards guide commerce-sdk prints:

## This project's setup

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

- Stores: all of them (18+), 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.
- Sandbox credentials: run `agent-cards credentials --mode sandbox`. ...

Run it without a terminal

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

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:

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
  --yes to install, or --skip-install
Example: agent-cards init --categories all --implementation tool --wallet vault --yes

--implementation api is refused until the API arrives:

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 says yes to the install and to Agentcard’s agent. The question about uncommitted changes is still asked.

CLI

Get access

Build

Operate

Answer the three questions

Install the SDK

Let Agentcard’s agent build it in

Know what the agent can touch

Use your own coding agent

Run it without a terminal

​Answer the three questions

​Install the SDK

​Let Agentcard’s agent build it in

​Know what the agent can touch

​Use your own coding agent

​Run it without a terminal

Answer the three questions

Install the SDK

Let Agentcard’s agent build it in

Know what the agent can touch

Use your own coding agent

Run it without a terminal