agent-cards-admin

The Agentcard B2B admin CLI: organizations, OAuth clients, members, webhooks, and the integration wizard. Agentcard issues virtual cards that AI agents can pay with; your app integrates once and every user gets per-user cards.

npm install -g agent-cards-admin    # or run everything via npx

Docs: docs.agentcard.sh · Wizard guide: docs.agentcard.sh/companies/getting-started/wizard

Fastest path: the wizard

wizard runs an AI integration agent (on Agentcard's tokens, you bring no Anthropic key) inside your repo. It signs you in, provisions an organization and a confidential OAuth client, writes the credentials to your app's env file (.env.local or .env, chmod 600, never shown to the AI or printed), implements the Connect with Agentcard OAuth flow plus MCP card issuance, and verifies it by issuing a sandbox card. All edits are left uncommitted for review.

If you are a coding agent (or driving one), this is the whole setup:

npx agent-cards-admin wizard --agent --yes --email [email protected] --app-url http://localhost:3000

Wizard agent contract

Modes. Agent mode (no prompts, plain line output) auto-enables when --agent is passed, AGENT_CARDS_WIZARD_MODE=agent is set, CLAUDECODE/CLAUDE_CODE is set (Claude Code), CI is set, or stdin/stdout is missing a TTY on either side. AGENT_CARDS_WIZARD_MODE=interactive forces the interactive UI. Anything missing exits 2 with the flag to add; an exit-2 run provisions nothing.

Flags.

| Flag | Meaning | |---|---| | --path <dir> | Target repo (default: current directory). Validated before any network call | | -y, --yes | Consent to modify files and write secrets locally. Required in agent mode | | --agent | Force agent mode | | --email <email> | Sign-in address when no session exists | | --code <code> | Finish a code sign-in after a code_required exit | | --org <id-or-name> | Organization to provision under (only when the account has several) | | --app-url <url> | App base URL for the OAuth callback (default http://localhost:3000) | | --app-name <name> | Name for the org (when created), OAuth client, and key (default: the repo directory name) | | --verbose | Include tool inputs and outputs in the stream |

Sign-in. With no session, a magic link is emailed to --email and the wizard polls for up to 15 minutes (override with AGENT_CARDS_WIZARD_LOGIN_TIMEOUT_MS, in milliseconds), riding out transient backend errors with backoff. Re-runs RESUME a pending sign-in instead of re-emailing; if extra emails were sent anyway, click the newest. Backends using code sign-in exit 2 with code_required; finish with --email <email> --code <code>. An existing agent-cards-admin login session or an exported AGENT_CARDS_ADMIN_JWT skips sign-in.

Duration. Runs take 5 to 20 minutes end to end. Use a 20+ minute timeout or run in the background. A heartbeat line prints during silence in every phase: … still working (3:42 elapsed; thinking). If the stream prints a connect link that needs a user tap, open it so the run can continue.

Result line. The last stdout line is always machine-readable, on success, failure, and crashes:

AGENTCARD_WIZARD_RESULT {"ok":true,"runId":"…","orgId":"…","orgName":"…","clientId":"…","redirectUri":"…","appBaseUrl":"…","envFile":".env.local","connectUrl":"…","credentialsReused":false,"numTurns":41,"elapsedSeconds":612}

credentialsReused is true when the wizard reused a valid OAuth client + key already in your env instead of minting new ones, so re-runs are idempotent (no orphaned credentials pile up). Success may add warnings (e.g. ["not_a_git_repo"]). Failures are {"ok":false,"error":"<code>","runId":"…"} plus hint, orgs (on org errors), a bounded message, and probableCause (gateway_disabled | daily_limit_exceeded | gateway_unconfigured | auth_expired_mid_run) when applicable. Secrets never appear in the stream or the result line.

Exit codes. 0 success · 1 integration/unexpected error · 2 missing input or consent.

Error codes. consent_required, login_required, code_required, invalid_email, invalid_path, invalid_app_url, invalid_app_name, org_ambiguous (result carries the orgs list), org_not_found (same), root_unsupported (run as non-root, or in a container where the wizard sandboxes itself), integration_agent_error, unexpected_error.

Env vars.

| Var | Effect | |---|---| | ADMIN_API_URL | API base URL (default https://api.agentcard.sh) | | AGENT_CARDS_ADMIN_JWT | Bearer token to use instead of a stored login session | | AGENT_CARDS_WIZARD_MODE | agent or interactive; overrides wizard mode auto-detection | | AGENT_CARDS_WIZARD_LOGIN_TIMEOUT_MS | Sign-in polling window in milliseconds (default 15 minutes) | | DO_NOT_TRACK=1 or AGENT_CARDS_TELEMETRY=0 | Disable telemetry (lifecycle events and error reports; never repo contents, paths, or secrets) |

Other commands

login, logout, orgs, oauth-clients, wallet, members, webhooks, cards, cardholders, payment-methods, subscribe, env, and the retired keys (legacy API keys no longer authenticate — use oauth-clients). Run agent-cards-admin <command> --help for details, or see docs.agentcard.sh.