agentagon-cli

The agentagon console script. Two surfaces: a buyer flow for agent onboarding, wallets, PATs, and paying x402 endpoints; and a seller flow for service registration, endpoint pricing, payouts, and ledger views.

Overview

Use agentagon-cli when you want to:

• Onboard a buyer agent in under a minute (agentagon init)
• Register a service for payments (agentagon service init)
• Mint and rotate PATs without touching the dashboard
• Pay an x402 endpoint from the terminal (agentagon buy)
• Read the ledger or run verification on a registered service
• Move between multiple profiles (dev / prod, multiple accounts) on one machine

It’s not the right tool when you want to:

• Embed payment middleware in your app: use agentagon.seller (Python) or @agentagon/sdk/seller (Node)
• Drive payment from inside an LLM client: use the MCP servers
• Programmatically read transactions or run verification: use agentagon.sdk.Client

Install

pip install agentagon-cli

agentagon-cli depends on agentagon; installing the CLI gives you the library too.

Quickstart

Buyer onboarding

agentagon init

Walks through:

1. Generate a BIP39 seed (or restore one with --restore)
2. Derive Base + Solana addresses (--chain {base,solana,both})
3. Run SIWE/SIWS attestation against the platform
4. Auto-spawn an agent and persist the config under ~/.agentagon/agents/
5. Mint a PAT and write it to the local profile

Once that’s done, you can pay any x402 endpoint:

agentagon buy https://demo-weather.agentagon.ai/v1/weather/sf --max 0.10

Seller registration

agentagon init is the canonical bootstrap and must run first for the seller flow too: it mints the account session (as_*) that service init needs.

agentagon init                               # bootstrap account
agentagon service init \
  --name "weather-api" \
  --openapi-url https://my-api.example.com/openapi.json \
  --capability weather.current

Returns the new seller_id and a service-scoped PAT. Subsequent service * commands read the PAT from the active service automatically.

Commands

Buyer / account

Seller / service

Deprecated

Two modes

Interactive

Run any command without all flags and you get prompts:

agentagon init
# Walks through seed gen, label, chain choice...

For human users.

Agent mode

Provide every required flag plus --json for machine-readable output:

agentagon service init \
  --name weather-api \
  --capability weather.current \
  --openapi-url https://example.com/openapi.json \
  --json

For AI agents driving the CLI (Claude Code, Cursor, Codex). Use --json everywhere you want structured output.

Files

Authentication

agentagon init is the canonical bootstrap for both buyer and seller flows. On first run it:

1. Generates a BIP39 seed + derives Base + Solana addresses
2. Runs SIWE/SIWS against /v1/identity/init, then auto-spawns an agent
3. Writes the agent config to ~/.agentagon/agents/<id>.json, sets active pointer
4. Persists the returned account-session token (as_*) to ~/.config/agentagon/session.json

agentagon service init is the seller-side bootstrap. It posts to POST /v1/sellers with the cached as_*, receives {seller_id, pat, ...}, stores the per-service record, sets the active-service pointer.

When the cached as_* is missing or expired, the CLI silently calls POST /v1/identity/exchange-pat with the active agent’s PAT to mint a fresh session, then retries. No user prompt unless the agent PAT itself is gone.

agentagon login --token ag_pat_... writes a PAT to ~/.config/agentagon/credentials.json so any tool that reads the same profile (the buyer MCP, for example) doesn’t need re-exported env vars.

Cookbook

Multiple profiles (dev + prod)

AGENTAGON_ENV=dev  agentagon init
AGENTAGON_ENV=prod agentagon init
agentagon profile list
agentagon profile switch prod

AGENTAGON_ENV={dev,prod,qa,preprod} picks which .env.{env} file is loaded at startup. agentagon status prints the active env + Supabase project ref on its first line.

Pay an endpoint with body data

agentagon buy https://api.example.com/v1/translate \
  --method POST \
  --body @./payload.json \
  --max 0.05

--body @file.json reads from a file. Plain --body '{"text": "hi"}' works for short payloads.

Drive the dashboard from a terminal

agentagon dashboard
# Opens https://app.agentagon.ai/cli-handoff#pat=<single-use-PAT>

The CLI mints a single-use PAT and opens the dashboard at the handoff page. The dashboard exchanges the single-use PAT for a session, then redirects to the same agent the CLI is on.

Spin up a service in CI

# Bootstrap (one-time per CI account)
agentagon init --json --label ci-bot --chain base --new-seed
 
# Register a service per-deploy
agentagon service init \
  --name "$SERVICE_NAME" \
  --openapi-url "$OPENAPI_URL" \
  --capability "$CAPABILITY" \
  --json > /tmp/service.json
 
# Extract the PAT for the running app
PAT=$(jq -r .pat /tmp/service.json)

--json everywhere produces machine-parseable output. The PAT lives in ~/.agentagon/services/<seller_id>.json after the call returns; you can also read it from there.

Sweep a stale config

agentagon agent list
agentagon agent delete <agent_id>           # local-only delete

Local-only agent operations (list, switch, label, delete) don’t hit the platform; they just clean up ~/.agentagon/agents/. Use agentagon agent show to confirm the platform’s view.

Multi-endpoint pricing

agentagon endpoints add --path /v1/cheap --price 0.001
agentagon endpoints add --path /v1/expensive --price 0.10
agentagon endpoints update ep_xxx --price 0.05

Endpoint paths and prices map to route_prices in agentagon.seller. The middleware reads the active set from the platform on first request.

CSV export of revenue

agentagon ledger export --format csv > revenue.csv

Combines the transactions view with revenue aggregation. Useful for accounting + reconciliation.

Errors

The CLI exits with a non-zero status on failure. Common patterns:

Most commands accept --json to produce structured stderr on errors. Parse it for automation.

Troubleshooting

”no active agent / no active service”

You haven’t run agentagon init yet. The CLI’s seller flow requires an account session, which agentagon init mints. The buyer flow requires an active agent, which the same command spawns.

”Master keys are no longer accepted”

The platform hard-cut ag_live_sk_* on 2026-04-27. The CLI still detects legacy ~/.agentagon/config.json files and prints a migration hint. Run:

agentagon init                           # bootstrap a session
agentagon service pat create --label cli # mint a PAT for the CLI

Dashboard handoff doesn’t pick up my agent

The agentagon dashboard command mints a single-use PAT and opens a URL with #pat=... in the fragment. If the dashboard is loaded behind an auth proxy that strips fragments, the handoff fails. Open the URL in a browser directly.

agentagon verify fails with well_known_not_found

The seller URL doesn’t host .well-known/agentagon-verification.txt at the expected path. Either:

• Check the URL is right (no https://www. if you registered without www)
• Make sure your origin actually serves the file at /.well-known/agentagon-verification.txt
• Wait a few seconds if you just deployed; CDN cache may not have caught up

”Seed decryption failed”

The wrong passphrase. The CLI doesn’t track passphrase failures; just retry with the correct one. If you’ve truly lost the passphrase, the seed is unrecoverable; restore from your written-down 24-word backup with agentagon init --restore.

CLI commands time out against my local gate

The CLI talks to https://api.agentagon.ai by default. For local dev:

export AGENTAGON_API_URL=http://localhost:8000
agentagon status

Or set AGENTAGON_ENV=dev and configure the matching .env.dev file in the agentagon repo.

How does agentagon-cli differ from agentagon (the library)?

agentagon-cli is a terminal tool you install and run. It pulls in agentagon as a dependency, so the same pip install agentagon-cli gives you both the CLI and the Python library. If you only want to import the library (no agentagon console script), pip install agentagon directly.