@axon402/cli

Durable control-plane operator CLI for AXON — wallet lifecycle, deposits, allocations, and API key management.

AXON splits agent surfaces into a runtime plane (what a worker agent gets — a prepared wallet and a wallet-scoped runtime key) and a control plane (what operators use — org-wide credentials to provision and govern the workforce). @axon402/cli (axon-op) is the control-plane companion to the AXON dashboard: show wallets, deposit USDC, allocate from the vault, create new API keys.

Where @axon402/init is the one-shot runtime bootstrap for a brand-new agent wallet, @axon402/cli is the durable operator tool you run day-to-day once your organization exists. One key = one surface: the operator key you hand to axon-op auth login is never a runtime/agent credential, and vice versa. Never hand this CLI to an autonomous worker agent.

Install

npm install -g @axon402/cli

The binary is axon-op (not axon, which is owned by @axon402/init). Both packages can be installed side by side.

Requirements: Node.js >= 20.

Authentication

@axon402/cli authenticates with an operator API key — a long-lived key minted from the AXON dashboard (or from this CLI via axon-op keys create). There is no browser login flow.

axon-op auth login
# prompts for API URL (default: https://api.axon402.com) and your axon_sk_... key
# verifies the key via GET /v1/me
# writes ~/.axon/operator.json at chmod 0600

Headless / CI login

Interactive prompts are skipped when either flags or environment variables are provided. Use this form in CI, Docker builds, and any non-TTY shell:

# Flag form (both --flag value and --flag=value are accepted):
axon-op auth login --api-key axon_sk_... --api-url https://api.axon402.com

# Environment form:
AXON_API_KEY=axon_sk_... AXON_API_URL=https://api.axon402.com axon-op auth login

| Source | API URL | API key | | --- | --- | --- | | Flag | --api-url <url> | --api-key <key> | | Environment | AXON_API_URL | AXON_API_KEY |

API key resolution: --api-key → AXON_API_KEY → interactive prompt (TTY only). If no key is provided and stdin is not a TTY, the command exits non-zero with a clear error instead of hanging on a prompt.

API URL resolution (headless, i.e. when a key is supplied via flag or env): --api-url → AXON_API_URL → AXON_CLI_DEFAULT_ENDPOINT → https://api.axon402.com. No interactive URL prompt runs in headless mode, so piped stdin is never consumed as the URL. In the interactive TTY flow, the URL prompt still defaults to the same production URL and accepts overrides.

To verify your session at any time:

axon-op auth whoami

This re-checks your key against the backend. If the key has been rotated or revoked, you'll see a Session expired message and need to log in again.

Commands

| Command | Description | | --- | --- | | axon-op auth login | Interactively connect an operator API key | | axon-op auth whoami | Print the current login context | | axon-op wallets show <wallet-id> | Show wallet metadata + funding status | | axon-op wallets deposit <wallet-id> | Render a QR code for external USDC deposit | | axon-op wallets allocate <wallet-id> --amount <usdc> | Move USDC from the org vault to the wallet (full-signed orgs only) | | axon-op keys create --name <name> [--wallet <id>] [--scopes read,write] | Mint a new API key |

Funding: deposit vs allocate

AXON supports two wallet-funding paths:

• External deposit — send USDC from any wallet app on Base to the wallet's deposit address. Works for every org regardless of signing mode. Use axon-op wallets deposit.
• Vault allocation — move USDC from the org's vault wallet into an agent pocket, signed server-side. Only available for full-signed orgs. Browser-signed orgs get a structured VAULT_ALLOCATION_UNAVAILABLE error and are directed back to external deposit.

axon-op wallets show tells you which path is available for a given wallet.

Configuration

~/.axon/operator.json

| Path | Permissions | Contents | | --- | --- | --- | | ~/.axon/operator.json | 0600 | { api_url, api_key, organization_id, organization_name, signing_mode, wallet_id, created_at } |

Writes are atomic (tmp + rename) so a crash mid-write can't leave a half-written file in place of the previous good one.

This file is separate from ~/.axon/config.json, which is owned by @axon402/init. The two CLIs do not share state — you can log in and out of @axon402/cli without disturbing the init CLI's wallet bootstrap.

Environment variables

| Var | Description | | --- | --- | | AXON_API_KEY | Operator API key used by axon-op auth login in headless mode. Overridden by --api-key. | | AXON_API_URL | API URL used by axon-op auth login in headless mode. Overridden by --api-url. | | AXON_CLI_DEFAULT_ENDPOINT | Override the default API URL (https://api.axon402.com). Useful for local dev and CI. |

TODO (not yet implemented)

• axon-op wallets list — blocked on a backend endpoint (GET /v1/orgs/:id/wallets) that does not yet exist for API-key auth. The platform uses a Supabase RPC that requires a user JWT. For now, you can see the wallet your key is bound to via axon-op auth whoami and inspect individual wallets via axon-op wallets show <id>.
• axon-op wallets create — blocked on POST /v1/wallets.
• axon-op auth logout — trivial wrapper over deleteOperatorConfig; will land in a follow-up.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Recoverable failure (invalid input, backend error, not logged in) | | 130 | SIGINT (Ctrl+C aborted a prompt) |

IDE-native operator automation (advanced)

axon-op is the durable control-plane CLI and the right tool for day-to-day operator work. For trusted developer workflows that need the same control-plane actions from within an MCP-speaking IDE (Claude Code, Cursor, VSCode), AXON also ships an explicit operator / manage MCP surface. It is advanced and opt-in — see mintlify-docs/integrations/ide-setup.mdx ("Advanced: Operator / manage surface") for the launch contract and per-IDE config. It is separate from axon-op and must be mounted under an org-wide operator key, never a runtime/wallet-scoped key.

Links

• Docs: https://axon402.com/docs/cli
• Dashboard: https://axon402.com
• Source: https://github.com/alex-reysa/AXON/tree/main/axon-cli-operator
• Issues: https://github.com/alex-reysa/AXON/issues

License

Apache-2.0 — see LICENSE.