CLI Reference: @axon402/init

@axon402/init is a one-shot runtime bootstrap helper. It provisions a wallet, mints a wallet-scoped runtime key for that wallet, and wires Claude Code to AXON’s hosted runtime MCP surface. This page is the canonical reference for all flags and behaviors of the bootstrap command.

@axon402/init lives on the runtime side of the runtime / control-plane split. The credential it issues is a runtime key — it is for an agent to use a prepared wallet, not an operator or org-admin credential. For durable operator work (additional wallets, key rotation, deposits, vault allocations) use @axon402/cli (axon-op) or the dashboard; both are documented on the CLI installation page. This reference covers @axon402/init only.

@axon402/init writes ~/.claude.json; it does not configure Cursor, VSCode, OpenClaw, or raw REST clients for you. Those integrations should still use the generated wallet_id and api_key from ~/.axon/config.json with the manual hosted setup in IDE Setup, OpenClaw Plugin, or REST API Integration.

Synopsis

npx @axon402/init [options]

Options

Flag	Description
`--version`	Print version and exit
`--help`, `-h`	Print help and exit
`--json`	Machine-readable JSON output (no prompts). Suitable for scripting. The `api_key` is intentionally NOT included in the JSON output — it’s persisted to `~/.axon/config.json` only.
`--email <email>`	Email address for headless / `--json` mode.
`--endpoint <url>`	Override the Decision API endpoint. Default: `https://api.axon402.com`
`--raw-qr`	Encode the bare `0x…` address in the QR instead of an EIP-681 URI
`--no-open`	Do not open the dashboard URL in a browser after success
`--force`	Overwrite an existing `~/.axon/config.json`. The prior file is copied to `~/.axon/config.json.bak-<ISO8601>` first. Without this flag, the CLI refuses to overwrite and exits non-zero.

Examples

# Default interactive flow against production
npx @axon402/init

# Emit machine-readable output
npx @axon402/init --json --email you@example.com

# Local Decision API for development
npx @axon402/init --endpoint http://localhost:3030

# Raw 0x QR code for wallets that don't parse EIP-681
npx @axon402/init --raw-qr

# Skip the browser auto-open at the end
npx @axon402/init --no-open

Environment variables

Variable	Description
`AXON_ENDPOINT`	Equivalent to `--endpoint`. Overridden by the flag if both are set.
`AXON_CLI_DEFAULT_ENDPOINT`	Same as `AXON_ENDPOINT`, kept for legacy reasons.
`AXON_EMAIL`	Email address for headless / `--json` mode. Overridden by `--email`.

Files written

Path	Permissions	Contents
`~/.axon/config.json`	`0600`	`{ organization_id, wallet_id, api_key, funding_address, dashboard_url, created_at }`
`~/.axon/config.json.bak-<ISO8601>`	inherits source file	Backup of the previous config when `--force` replaces an existing file
`~/.claude.json`	unchanged	Claude Code only. New `mcpServers.axon` entry merged in with `url: <endpoint>/v1/mcp` and `Authorization: Bearer <runtime-key>`
`~/.claude.json.bak-<ts>`	unchanged	Backup of `~/.claude.json` from before the merge

Exit codes

Code	Meaning
`0`	Success
`1`	Unexpected error (network failure, server 5xx, validation crash)
`130`	SIGINT (Ctrl+C aborted the prompt)

JSON output mode

When invoked with --json, the CLI emits a single JSON object to stdout on success and exits 0. No interactive prompts; provide the email with --email or AXON_EMAIL.

{
  "ok": true,
  "organization_id": "uuid",
  "wallet_id": "uuid",
  "funding_address": "0x…",
  "dashboard_url": "https://axon402.com",
  "config_path": "~/.axon/config.json",
  "config_backup_path": null,
  "claude_config_path": "~/.claude.json",
  "claude_backup_path": null
}

config_backup_path is non-null only when --force replaced an existing ~/.axon/config.json. claude_backup_path is non-null only when ~/.claude.json already existed and was backed up before the merge.

The api_key is intentionally absent from the JSON output. It is written only to ~/.axon/config.json (chmod 0600). This avoids leaking the plaintext key into shell pipelines, CI logs, or terminal scrollback.

Troubleshooting

`Mandate missing for wallet`

You’re on a CLI build older than v0.1.0 where the API key was bound to the vault wallet by mistake. Vault wallets have no mandate by design, so every governed_fetch call against a vault-bound key fails with this error. Fix: upgrade to ≥ v0.1.0:

npm install -g @axon402/init@latest
axon

This generates a new wallet bound correctly to the agent (HD index 1).

`409 CONFLICT — An account already exists for this email`

Self-explanatory — @axon402/init is a one-shot runtime bootstrap and it has already run for this email. It is not for ongoing operations and it is not an operator CLI; to manage the existing account from the terminal, install @axon402/cli (axon-op) instead, or sign in to the dashboard via the printed dashboard_url.

{
  "code": "CONFLICT",
  "message": "An account already exists for this email.",
  "details": {
    "dashboard_url": "https://axon402.com",
    "login_hint": "Sign in to the dashboard to retrieve or rotate your API key."
  }
}

`429 RATE_LIMITED`

The endpoint is limited to 10 requests per hour per IP to prevent spam signups. The CLI prints a retry_after_seconds value — wait that long and try again. If you’re hitting this in legitimate dev (e.g., scripted CI), use --endpoint to point at a local Decision API instead.

`NETWORK_ERROR — Could not reach https://api.axon402.com`

Outbound HTTPS to api.axon402.com is blocked or the public Decision API is down. Check:

Status: curl -i https://api.axon402.com/ready should return a structured HTTP response if the service is reachable. 200 means ready; 503 still proves the network path works and the backend is just not ready.
Network: corporate firewalls sometimes block npm-installed binaries from making HTTPS calls. Try from a different network.
Local fallback: for development, run a Decision API locally and use --endpoint http://localhost:3030.

`~/.claude.json already exists`

The CLI merges new MCP entries into your existing ~/.claude.json — it does not overwrite. Before writing, it backs up the original to ~/.claude.json.bak-<unix-timestamp>. If something looks wrong after running the CLI, restore from the backup:

ls -lt ~/.claude.json.bak-* | head -1
cp ~/.claude.json.bak-<ts> ~/.claude.json

“I want to reset and start over”

Delete the CLI’s local state and re-run:

rm -rf ~/.axon/
# Optional: revert ~/.claude.json from a backup
ls -lt ~/.claude.json.bak-* | head -1
npx @axon402/init

Note: this does NOT delete the Supabase auth user, the organization, or the wallets on the server. You’ll get a 409 CONFLICT next time unless you use a different email. The dashboard at https://axon402.com is the place to manage server-side state.

What gets written to Claude Code

@axon402/init does not write a local stdio launch command. It merges a hosted HTTP MCP entry into ~/.claude.json that points Claude Code at the Decision API directly:

{
  "mcpServers": {
    "axon": {
      "url": "https://api.axon402.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer axon_sk_..."
      }
    }
  }
}

If you want to run the local MCP server over stdio instead, use the advanced self-hosted patterns in IDE Setup and MCP Server. Those are separate from the hosted HTTP config that @axon402/init writes automatically.

Getting Started

CLI

Core Concepts

Integrations

Operations

CLI Reference: @axon402/init

Synopsis

Options

Examples

Environment variables

Files written

Exit codes

JSON output mode

Troubleshooting

`Mandate missing for wallet`

`409 CONFLICT — An account already exists for this email`

`429 RATE_LIMITED`

`NETWORK_ERROR — Could not reach https://api.axon402.com`

`~/.claude.json already exists`

“I want to reset and start over”

What gets written to Claude Code

See also

​Synopsis

​Options

​Examples

​Environment variables

​Files written

​Exit codes

​JSON output mode

​Troubleshooting

​Mandate missing for wallet

​409 CONFLICT — An account already exists for this email

​429 RATE_LIMITED

​NETWORK_ERROR — Could not reach https://api.axon402.com

​~/.claude.json already exists

​“I want to reset and start over”

​What gets written to Claude Code

​See also

Synopsis

Options

Examples

Environment variables

Files written

Exit codes

JSON output mode

Troubleshooting

`Mandate missing for wallet`

`409 CONFLICT — An account already exists for this email`

`429 RATE_LIMITED`

`NETWORK_ERROR — Could not reach https://api.axon402.com`

`~/.claude.json already exists`

“I want to reset and start over”

What gets written to Claude Code

See also