The Wizard

The wizard is the fastest way to integrate. It’s an AI agent that implements the whole integration, the “Connect with Agentcard” OAuth flow plus per-user card issuance via the MCP server, directly in your repository, then proves it by issuing a real card in test mode. You don’t bring a key for the agent: the wizard runs on Agentcard’s own tokens through a hosted gateway.

Run it

npm install -g agent-cards
cd /path/to/your/app
agent-cards companies wizard

The wizard:

Forces test mode for the run. No real money can move.
Detects your stack (framework, package manager, any existing OAuth or MCP code) and asks for consent before provisioning anything or touching files.
Signs you in if needed (a one-time code we email you), then provisions your company and a confidential OAuth client with test credentials. The secrets go straight into your app’s env file (.env.local or .env, chmod 600) and are never shown to the AI.
Makes minimal, idiomatic edits following the Agentcard integration playbook.
Verifies the integration by issuing a test card, then prints a summary of every file it changed, plus your account dashboard link (app.agentcard.sh/org/<orgId>) where you can see the cards, balance, and OAuth client it set up.

All edits are left uncommitted. Review the diff and commit; that’s the whole integration.

Options

Flag	What it does
`--path <dir>`	Target a repo other than the current directory
`-y, --yes`	Skip the consent prompt. Required in agent mode: it is the explicit consent to modify files
`--agent`	Force non-interactive agent mode (usually auto-detected, see below)
`--email <email>`	Email for sign-in when no session exists. Interactive runs prefill the sign-in prompt with it (and offer to switch accounts if you’re signed in as someone else)
`--code <code>`	Agent mode: finish a code sign-in after a `code_required` exit. Interactive runs prompt for the code directly
`--org <id-or-name>`	Company to provision under. Agent mode: only needed when your account has several. Interactive runs skip the company picker when it matches
`--app-url <url>`	Your app’s base URL for the OAuth callback (default `http://localhost:3000`)
`--app-name <name>`	Name for the company (when created) and OAuth client (default: the repo directory name)
`--verbose`	Include tool inputs and outputs in the stream

Agent mode

The wizard is built to be driven by another AI agent (Claude Code, Cursor, a CI job). In agent mode it never prompts: every input is a flag, progress streams as plain lines, and the run always ends with a single machine-readable result line. Agent mode turns on automatically when any of these is true:

--agent is passed
AGENT_CARDS_WIZARD_MODE=agent is set
CLAUDECODE or CLAUDE_CODE is set (Claude Code exports these)
CI is set
stdin or stdout is not a TTY

Set AGENT_CARDS_WIZARD_MODE=interactive to force the interactive UI back on (for example, a human piping output through tee). The copy-paste invocation:

npx agent-cards companies wizard --agent --yes --email you@company.com --app-url http://localhost:3000

Driving the wizard from a coding agent. Runs take 5 to 20 minutes end to end, so use a generous timeout (20+ minutes) or run it in the background. Re-running is safe and resumable: a pending sign-in resumes instead of re-emailing, and every exit-2 result carries a hint naming the missing flag — and, when the value isn’t derivable, what to ask your user (the emailed sign-in code, which organization, the app’s base URL). Resolve it in your own conversation, then re-run with that flag. Add --verbose to stream tool inputs and outputs. If the stream prints a connect link that needs a user tap, open it so the run can continue. On success, hand your user the dashboardUrl from the result line — it’s their account view (cards, balance, billing) for everything the wizard set up.

With no existing session, the wizard emails a one-time code to --email. Interactive runs prompt for the code in place; in agent mode the run exits 2 with code_required and the driving agent asks its user for the code, then re-runs with --code. Re-runs resume a pending sign-in: if a driving agent times out and runs the wizard again, it continues the same session instead of sending a fresh, superseding email. If more than one email did get sent, use the newest one. Legacy backends that still sign in with a magic link are handled by polling: the wizard waits up to 15 minutes while someone clicks the link (override the window with AGENT_CARDS_WIZARD_LOGIN_TIMEOUT_MS, in milliseconds); transient backend errors during the wait are retried with backoff instead of failing the run. Against the current backend you finish a code sign-in with:

npx agent-cards companies wizard --agent --yes --email you@company.com --code 123456

An existing session (agent-cards login) or an exported AGENT_CARDS_JWT skips sign-in entirely.

Progress and the result line

While it works, the wizard streams plain progress lines, and during any silent stretch (in every phase, sign-in wait included) it prints a heartbeat so a driver can tell a pause from a hang:

… still working (3:42 elapsed; thinking)

The last stdout line is always machine-readable, on success and on every failure path, even a crash:

AGENTCARD_WIZARD_RESULT {"ok":true,...}

Grep for the AGENTCARD_WIZARD_RESULT prefix; the rest of the line is one JSON object. A success payload (pretty-printed here, the real thing is a single line):

{
  "ok": true,
  "runId": "3f8f9c9e-3f4b-4b7e-9a6d-2b1a7c5d9e10",
  "orgId": "cmcqi8dxr0001la047r8o5ykj",
  "orgName": "acme-shop",
  "clientId": "9b2f6a3e-8c1d-4f5a-b6e7-0d9c8b7a6f5e",
  "redirectUri": "http://localhost:3000/api/agentcard/callback",
  "appBaseUrl": "http://localhost:3000",
  "envFile": ".env.local",
  "connectUrl": "http://localhost:3000/api/agentcard/connect?user=<id>",
  "dashboardUrl": "https://app.agentcard.sh/org/cmcqi8dxr0001la047r8o5ykj",
  "credentialsReused": false,
  "numTurns": 41,
  "elapsedSeconds": 612
}

The sample shows the fields to build against; the result line can carry additional diagnostic fields — ignore any you don’t recognize. credentialsReused is true when the wizard found valid Agentcard credentials already in your env (from a previous run) and reused them instead of minting new ones. Re-runs are therefore idempotent: they do not pile up orphaned clients, and a multi-company account only needs --org on the first run (the saved credentials pin the company). A warnings array appears when there is something worth flagging, for example ["not_a_git_repo"] (the wizard still runs, you just lose the review-the-diff safety net). Failures look like {"ok":false,"error":"<code>","runId":"…"} plus what a driver needs to recover without scraping the stream. Every exit-2 (missing/bad input) failure carries a message saying what is wrong and a hint saying how to fix it — including what to ask your user when the value can’t be derived (the sign-in code from their inbox, which company the app belongs to, the app’s base URL). Relay that question, then re-run with the flag the hint names. Company-selection errors additionally carry the orgs list ([{id, name}]) so the user can pick from real options. Exit-1 failures carry a bounded message and, when the cause is recognizable, a probableCause (gateway_disabled, daily_limit_exceeded, gateway_unconfigured, or auth_expired_mid_run). Secrets never appear in the stream or the result line. The OAuth client credentials are written only to your app’s env file.

Exit and error codes

Both modes let the user complete these cases instead of dead-ending — they just do it through different surfaces. The interactive wizard prompts in place: a bad --path asks for the right directory, an over-long app name asks for a shorter one, an unknown --org falls back to the company picker, an invalid --app-url or --email falls back to the corresponding prompt, and a mistyped sign-in code re-prompts instead of failing the run. In agent mode the same resolution happens through the driving agent: the exit-2 result line carries message + hint (+ orgs on org errors) telling the driver exactly what to ask its user and which flag to re-run with, so the case gets solved in the driver’s own conversation.

Exit	Meaning
`0`	Success: the integration ran and verified
`1`	Integration or unexpected error; re-run with the same flags to retry
`2`	Missing input or consent; the result line names the flag to add. Nothing was provisioned

Error code	Exit	What to do
`consent_required`	2	Ask the user to approve file modifications, then re-run with `--yes`
`login_required`	2	Ask the user for their account email, then re-run with `--email <address>` (or export `AGENT_CARDS_JWT`)
`code_required`	2	A sign-in code was emailed; ask the user for the code from the newest email, then re-run with `--email <address> --code <code>`
`invalid_email`	2	Ask the user for their email address and fix the `--email` value
`invalid_path`	2	`--path` must be an existing, writable directory (checked before any network call); ask the user for the repo path if unknown
`invalid_app_url`	2	`--app-url` must be a URL like `http://localhost:3000`; ask the user for their app’s base URL
`org_ambiguous`	2	The account has several companies; ask the user which one (the result carries the `orgs` list), then re-run with `--org`
`org_not_found`	2	`--org` matched none of the account’s companies; ask the user to pick from the `orgs` list in the result
`invalid_app_name`	2	`--app-name` must be 89 characters or fewer
`root_unsupported`	2	Run as a non-root user, or inside a container (where the wizard sandboxes itself)
`integration_agent_error`	1	The integration agent stopped; the result carries `message` and, when known, `probableCause`
`unexpected_error`	1	Something else broke; the result carries `message`

Good to know

Re-running is safe. The wizard detects an existing integration and continues or fixes it; it never duplicates the integration.
You review everything. Edits happen locally and are left uncommitted; nothing ships until you commit.
It ends in test mode. Production credentials come with a company subscription (agent-cards companies subscribe) when you’re ready to go live.
Telemetry. The CLI reports lifecycle events (run started, phases, completion, with run id, error codes, and durations; never repo contents, paths, or secrets). Opt out with DO_NOT_TRACK=1 or AGENT_CARDS_TELEMETRY=0.

Prefer to wire things up yourself? Head to Manual Implementation.

Getting Started

Authentication

Guides

Webhooks

Funding options

Withdrawals

MCP

Examples

Run it

Options

Agent mode

Progress and the result line

Exit and error codes

Good to know

​Run it

​Options

​Agent mode

​Sign-in

​Progress and the result line

​Exit and error codes

​Good to know

Run it

Options

Agent mode

Sign-in

Progress and the result line

Exit and error codes

Good to know