> ## 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.

# Install the CLI

> Runtime bootstrap with @axon402/init and control-plane operations with @axon402/cli

AXON ships two CLIs that sit on opposite sides of the runtime / control-plane split. They do different jobs and are safe to install side by side.

| Package | Bin | Plane | Purpose |
| :- | :- | :- | :- |
| [`@axon402/init`](https://www.npmjs.com/package/@axon402/init) | `axon` | Runtime bootstrap | **One-shot runtime bootstrap.** Creates your first wallet, mints a wallet-scoped runtime key, and wires Claude Code's hosted MCP config so a worker agent can start spending. Run once. |
| [`@axon402/cli`](https://www.npmjs.com/package/@axon402/cli) | `axon-op` | Control plane | **Durable operator CLI.** Day-to-day wallet inspection, key rotation, deposits, allocations, and provider search against the hosted Decision API. Companion to the dashboard. |

> [!NOTE]
>
> The bin names are deliberately distinct (`axon` vs `axon-op`) so the two packages can be globally installed without colliding. The distinction also reflects trust: `axon` hands a worker agent a runtime credential; `axon-op` is an operator surface and should never be handed to an autonomous worker agent.

## Step 1: Runtime bootstrap with `@axon402/init`

`@axon402/init` is the canonical first-run runtime bootstrap helper. One command creates your first wallet, mints a wallet-scoped **runtime key** for that wallet, and wires **Claude Code** to AXON's hosted runtime MCP endpoint.

```bash theme={null}
npx @axon402/init
```

That's the whole thing. No global install required, no `.env`, no config file. The installer walks you through one prompt and writes the result to `~/.axon/config.json` (chmod 0600) plus a merged entry in `~/.claude.json`.

> [!NOTE]
>
> `@axon402/init` auto-configures **Claude Code only**. If you use Cursor, VSCode, OpenClaw, or direct REST instead, still run it first to mint the wallet and runtime key, then reuse the generated `wallet_id` and `api_key` from `~/.axon/config.json` in the manual setup flows under [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).

> [!WARNING]
>
> `@axon402/init` is a **one-shot runtime bootstrap**, not an ongoing CLI or an operator credential. It creates exactly one wallet and exactly one wallet-scoped runtime key. Re-running it for the same email returns `409 CONFLICT` by design. For every later operation — new wallets, new keys, deposits, allocations — use the dashboard or `@axon402/cli` (`axon-op`). The runtime key this step issues is intended for an agent to use the prepared wallet through MCP; it is not an operator/admin credential and does not give the agent control over the organization.

### What the installer does

1. **Generates a fresh wallet locally.** BIP-39 mnemonic, BIP-44 derivation. Two addresses: a **vault** (HD index 0, the deposit target) and an **agent** (HD index 1, the spend source). The mnemonic never leaves your machine.
2. **Bootstraps the org + agent + mandate.** `POST /v1/cli/init` sends your email and the two derived addresses. The server creates a Supabase auth user (and emails you a confirmation link), an organization, both wallets, and a starter spending mandate (10 USDC/day, 0.50/tx, 300/mo, hard-stop enforcement).
3. **Mints a wallet-scoped starter API key.** Bound to the **agent** wallet (not the vault — the vault has no mandate by design). Returned to the CLI exactly once and persisted to `~/.axon/config.json`.
4. **Wires Claude Code's MCP config.** Merges an HTTP entry for `https://api.axon402.com/v1/mcp` (or your `--endpoint` override) into `~/.claude.json`, backing the existing file up to `~/.claude.json.bak-<unix-timestamp>` first.
5. **Prints a deposit QR code.** Scan with Coinbase Wallet, Rainbow, or any Base-compatible wallet to deposit USDC to the vault on Base mainnet. This is an external on-chain transfer — it works the same in both signing modes.

### Files written

| Path | Permissions | Contents |
| - | - | - |
| `~/.axon/config.json` | `0600` | `{ organization_id, wallet_id, api_key, funding_address, dashboard_url, created_at }` |
| `~/.claude.json` | unchanged | Claude Code only. New hosted `mcpServers.axon` entry merged in. Original backed up to `~/.claude.json.bak-<unix-timestamp>` first. |

### Optional global install

If you want the `axon` binary on your PATH (rarely necessary — `npx` is the supported entry point):

```bash theme={null}
npm install -g @axon402/init
axon
```

## Step 2: The operator CLI

`@axon402/cli` is the **control-plane** operator CLI — the terminal companion to the dashboard. Everything that comes after the first wallet — additional wallets, key rotation, deposits, vault allocations, org context inspection — is its job. It is not a runtime surface and should not be handed to an autonomous worker agent.

```bash theme={null}
npm install -g @axon402/cli
```

> [!NOTE]
>
> `@axon402/cli` is the V1 operator CLI. It uses org-wide operator keys and is separate from the runtime key that `@axon402/init` writes for worker agents.

### What it's for

* **Auth against the hosted Decision API** with an organization-wide operator key (`axon_sk_*`) created from the dashboard or via `POST /v1/api-keys`.
* **Manage wallets**: list, show deposit addresses + QR, allocate from vault to pocket. Create new wallets in the dashboard for V1.
* **Rotate API keys**: create org-wide or wallet-scoped keys; list; mark compromised keys inactive.
* **Inspect org context**: dump the org id, signing mode, and scopes resolved from whatever key is logged in.
* **Operate the marketplace surface**: search providers.

### Current command surface

| Command | Purpose |
| :- | :- |
| `axon-op auth login [--api-url <url>] [--api-key <key>]` | Store an API key in `~/.axon/operator.json` (chmod 0600); interactive or headless |
| `axon-op auth whoami [--json]` | Resolve org id, signing mode, scopes, surface, and wallet binding from the stored key (`GET /v1/me`) |
| `axon-op auth logout [--yes]` | Delete the stored local credential |
| `axon-op wallets list [--json]` | List every wallet in the org |
| `axon-op wallets show <wallet_id> [--json]` | Pretty-print wallet details including deposit address and whether vault allocation is available |
| `axon-op wallets deposit <wallet_id>` | Print an ASCII QR for the wallet's deposit address so an external wallet app can scan it |
| `axon-op wallets allocate <wallet_id> --amount <amount_usdc>` | Vault -> pocket internal transfer (full-signed orgs only) |
| `axon-op keys create --name "ci" [--wallet <id>] [--scopes read,write]` | Mint a new API key. Omit `--wallet` for an org-wide operator key. |
| `axon-op keys list [--json]` | List API keys without ever re-showing plaintext secrets |
| `axon-op keys revoke <key_id> [--yes]` | Soft-revoke an API key (`is_active=false`), idempotently |
| `axon-op mandates list [--json]` | List mandates in the org |
| `axon-op ledger [--wallet <id>] [--limit <n>] [--json]` | List recent ledger entries |
| `axon-op approvals list [--json]` | List approval requests in the org |
| `axon-op providers search '<query>' [--wallet <id>] [--max-price <usdc>] [--explain] [--json]` | Search x402 providers via the Decision API |

### Authentication model

`@axon402/cli` uses **organization-wide operator API keys** as its primary credential. These are long-lived `axon_sk_*` tokens created either:

* From the dashboard at `/settings/api-keys`, or
* Via `POST /v1/api-keys` (see [API Keys reference](https://docs.axon402.com/docs/api-reference/organizations/create-api-key.md))

Both paths write to the `api_keys` table using the same HMAC-SHA256 hashing the Decision API uses on the read side, and the plaintext is returned to the caller exactly once.

> [!WARNING]
>
> The wallet-scoped starter key that `@axon402/init` writes to `~/.axon/config.json` is a **runtime key**. It is intended for an agent to call `governed_fetch` and the rest of the runtime MCP surface against the prepared wallet — it is not an operator credential. For daily control-plane ops, create an **org-wide** operator key from the dashboard or `POST /v1/api-keys` and hand it to `axon-op auth login`. One key = one surface.

If you do log in with a runtime key by mistake, `axon-op auth login` and `axon-op auth whoami` will show `surface: runtime`. Read-oriented commands remain available, but write paths such as `keys create`, `wallets allocate`, and `offers create` refuse with `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE` until you re-login with an org-wide key.

### Installation sanity check

```bash theme={null}
axon-op --version
axon-op auth login --api-key axon_sk_...
axon-op auth whoami
```

> [!NOTE]
>
> For IDE-native MCP-driven operator automation (a separate, advanced use case), the operator / manage MCP surface is documented separately in [Integrations → IDE Setup](https://docs.axon402.com/docs/integrations/ide-setup.md#advanced-operator-manage-surface-opt-in). Day-to-day operator work is still best done from `axon-op` or the dashboard.

`axon-op auth whoami` calls `GET /v1/me` on the hosted Decision API. A successful response tells you the org id, the org's signing mode (`full` or `browser`), and the scopes available to the key.

## Requirements (both CLIs)

* **Node.js**:
  `@axon402/init` requires `>=18`; `@axon402/cli` requires `>=20`
* **OS**: macOS, Linux, or WSL on Windows. Native Windows is untested but should work because neither CLI has native dependencies.
* **Network**: outbound HTTPS to `https://api.axon402.com` and `https://registry.npmjs.org`

## Next steps

* See the [CLI reference](https://docs.axon402.com/docs/cli/reference.md) for `@axon402/init` flags, environment variables, exit codes, and troubleshooting.
* See the [POST /v1/cli/init endpoint reference](https://docs.axon402.com/docs/api-reference/cli-init.md) for the API that `@axon402/init` calls.
* See [GET /v1/me](https://docs.axon402.com/docs/api-reference/organizations/me.md) for the auth introspection endpoint `@axon402/cli` uses at login.
* Sign in to the [hosted dashboard](https://axon402.com) (you'll receive a confirmation email) to view ledger entries, approve spend requests, and edit the mandate.


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