> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference: @axon402/init

> Flags, environment variables, exit codes, and troubleshooting for the @axon402/init runtime bootstrap helper

`@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.

> [!NOTE]
>
> `@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](https://docs.axon402.com/docs/cli/installation.md) page. This reference covers `@axon402/init` only.

> [!NOTE]
>
> `@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](https://docs.axon402.com/docs/integrations/ide-setup.md), [OpenClaw Plugin](https://docs.axon402.com/docs/integrations/openclaw-plugin.md), or [REST API Integration](https://docs.axon402.com/docs/integrations/rest-api.md).

## Synopsis

```bash theme={null}
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

```bash theme={null}
# 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`.

```json theme={null}
{
  "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.

> [!WARNING]
>
> 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:

```bash theme={null}
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:

1. **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.
2. **Network**: corporate firewalls sometimes block npm-installed binaries from making HTTPS calls. Try from a different network.
3. **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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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](https://docs.axon402.com/docs/integrations/ide-setup.md) and [MCP Server](https://docs.axon402.com/docs/integrations/mcp-server.md). Those are separate from the hosted HTTP config that `@axon402/init` writes automatically.

## See also

* [Install the CLI](https://docs.axon402.com/docs/cli/installation.md) — side-by-side overview of `@axon402/init` (runtime bootstrap) and `@axon402/cli` (control-plane operator CLI)
* [`@axon402/cli`](https://docs.axon402.com/docs/cli/installation#step-2-the-operator-cli) — the durable operator CLI for wallets, keys, deposits, and vault allocations (control plane)
* [MCP Server](https://docs.axon402.com/docs/integrations/mcp-server.md) — the runtime-plane surface the issued runtime key is for
* [POST /v1/cli/init](https://docs.axon402.com/docs/api-reference/cli-init.md) — the underlying server endpoint for `@axon402/init`
* [POST /v1/api-keys](https://docs.axon402.com/docs/api-reference/organizations/create-api-key.md) — mint org-wide operator keys for `@axon402/cli`
* [GET /v1/me](https://docs.axon402.com/docs/api-reference/organizations/me.md) — the auth introspection endpoint `@axon402/cli` uses at login
* [Quickstart](https://docs.axon402.com/docs/getting-started/quickstart.md) — the higher-level get-started page


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.