agent-cards

The Agentcard CLI. One product, two doors: Personal gives your own AI agent a card; companies issues cards to every agent your users run. Also installed as agentcard.

npx -y agent-cards@latest              # guided setup: sign in, connect your agent, fund — and it offers to install itself
npx -y agent-cards@latest agents add   # teach your coding agents (Claude Code, Codex, Gemini) to use Agentcard

Or install directly: npm install -g agent-cards.

Docs: docs.agentcard.sh

Personal — a card for your agent

agent-cards login                      # emails you a one-time code
agent-cards setup-mcp                  # add the Agentcard MCP to Claude Code (OAuth, no tokens to manage)
agent-cards fund --amount 20           # add cash to your balance (Apple/Google Pay)
agent-cards cards create --amount 25   # issue a one-time virtual card from your balance
agent-cards buy "paper towels from Costco on DoorDash"

Sign-in emails a code (no passwords, no magic links). Driving the CLI as an agent without a terminal:

agent-cards login --email [email protected]          # emails a code, exits 2 with code_required
agent-cards login --email [email protected] --code 123456

Everything else: agent-cards --help (wallet = your cards + balance; rewards, buy, kyc, plan, connections, support).

Companies — issue cards to your users' agents

Everything that used to live in agent-cards-admin (still published as a forwarding shim, so old commands keep working):

agent-cards companies wizard           # AI agent implements Agentcard (OAuth + MCP) into your repo
agent-cards companies create           # create a company
agent-cards companies use acme         # set the default company (like the dashboard switcher)
agent-cards companies credentials create   # client credentials for your servers (API keys are retired)
agent-cards companies balance get
agent-cards companies subscribe        # unlock production

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

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

Companies 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> | Company 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 company (when created) and OAuth client (default: the repo directory name) | | --verbose | Include tool inputs and outputs in the stream |

Sign-in. With no session, a sign-in email goes 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, use the newest. Backends using code sign-in exit 2 with code_required; finish with --email <email> --code <code>. An existing agent-cards login session or an exported AGENT_CARDS_JWT (legacy AGENT_CARDS_ADMIN_JWT still honored) 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 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 | |---|---| | AGENT_CARDS_API_URL | API base URL (default https://api.agentcard.sh; legacy ADMIN_API_URL still honored for companies commands) | | AGENT_CARDS_JWT | Bearer token to use instead of a stored login session (legacy AGENT_CARDS_ADMIN_JWT still honored) | | AGENT_CARDS_MCP_URL | MCP server URL override (default derived from the API URL) | | 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) | | AGENT_CARDS_SKIP_UPDATE=1 | Skip the pre-command auto-update check (also skipped under CI) | | DO_NOT_TRACK=1 or AGENT_CARDS_TELEMETRY=0 | Disable telemetry (lifecycle events and error reports; never repo contents, paths, or secrets) |

One config, one session

Credentials live in ~/.agent-cards/config.json (0600). Signing in once covers both doors — companies are created from your account. An existing ~/.agent-cards-admin.json session is adopted automatically the first time the unified CLI runs.