> For the complete documentation index, see [llms.txt](https://docs.vapinetwork.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vapinetwork.ai/reference/cli-reference.md).

# CLI reference

The vapi CLI reference documents commands, options, environment variables, and exit codes for local wallets and API payments.

{% hint style="info" %}
vAPI Router, Stake and Agents are coming soon. This page describes how they work at launch.
{% endhint %}

This page is for developers and operators who need every `vapi` command, option, environment variable, and exit code.

The CLI manages vault accounts, moves USDC, pays x402 APIs, runs agents and swarms, and publishes APIs. New users can start with the [Overview Quickstart](https://docs.vapinetwork.ai/quickstart).

```bash
npm i -g vapi-network
vapi init
```

This installs the current 0.7.0 release. Install the 0.8.0 preview for commands marked below:

```bash
npm i -g vapi-network@next
```

Most commands use `--json` for structured output. Receipt exports use `--format json` or `--format csv`. Exit codes are `0` for success, `1` for an operational failure, and `2` for invalid usage or an announced preview-only command. `vapi mcp --json` is accepted as a no-op because the stdio transport is already JSON-RPC.

## Setup

### `vapi init`

Creates `~/.vapi`, the vault account `main`, and the config. Says so if one exists.

| Option                  | What it does                 | Default |
| ----------------------- | ---------------------------- | ------- |
| `--networks <base,arc>` | Enables the listed networks. | Base    |

```bash
vapi init --networks base,arc
```

### `vapi setup`

Creates or completes the device vault, first account, and owner link

| Option              | What it does                              | Default                       |
| ------------------- | ----------------------------------------- | ----------------------------- |
| `--no-cloud-backup` | Skips the interactive cloud-backup offer. | Offers enrollment after setup |

```bash
vapi setup --no-cloud-backup
```

### `vapi fund`

Prints and opens the hosted funding page. Makes no network call.

| Option             | What it does                                     | Default                                                  |
| ------------------ | ------------------------------------------------ | -------------------------------------------------------- |
| `--amount <usd>`   | Prefills a US dollar amount on the funding page. | Not stated in the source                                 |
| `--account <name>` | Selects the account to fund.                     | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi fund --amount 25 --account main
```

### `vapi accounts`

Lists local vault accounts, balances, links, caps, and ceilings

| Option  | What it does                                                  | Default             |
| ------- | ------------------------------------------------------------- | ------------------- |
| `--all` | Adds the owner's accounts on other devices as read-only rows. | Local accounts only |

```bash
vapi accounts --all
```

## Accounts and transfers

### `vapi accounts add <name>`

Adds a derived account and starts its owner link

| Option           | What it does                                 | Default                  |
| ---------------- | -------------------------------------------- | ------------------------ |
| `--label <text>` | Sets the account label.                      | Not stated in the source |
| `--no-link`      | Creates the account without starting a link. | Starts a link            |

```bash
vapi accounts add researcher --label "research agent"
```

### `vapi accounts import <name>`

Imports one private key as a vault account

| Option              | What it does                        | Default                   |
| ------------------- | ----------------------------------- | ------------------------- |
| `--keystore <path>` | Reads an encrypted legacy keystore. | Prompts for a private key |
| `--key-file <path>` | Reads the private key from a file.  | Prompts for a private key |
| `--label <text>`    | Sets the account label.             | Not stated in the source  |

```bash
vapi accounts import legacy --keystore ./legacy.json
```

### `vapi accounts rename|use|remove|restore`

Renames an account, selects the default, moves an account to trash, or restores it

| Command or option                  | What it does                                             | Default                      |
| ---------------------------------- | -------------------------------------------------------- | ---------------------------- |
| `vapi accounts rename <old> <new>` | Renames the account and its local references.            | Not applicable               |
| `vapi accounts use <name>`         | Makes the account the default.                           | Not applicable               |
| `vapi accounts remove <name>`      | Removes the account after terminal confirmation.         | Refuses without confirmation |
| `--force`                          | Removes the named account without terminal confirmation. | Off                          |
| `vapi accounts restore <name>`     | Restores a removed account.                              | Not applicable               |

```bash
vapi accounts rename old-name new-name
vapi accounts use researcher
vapi accounts remove retired-account --force
vapi accounts restore retired-account
```

### `vapi accounts caps <name>`

Sets local spend caps and the automatic Base USDC ceiling

| Option                 | What it does                                           | Default                 |
| ---------------------- | ------------------------------------------------------ | ----------------------- |
| `--per-call <usd>`     | Sets the maximum for one paid call or capped transfer. | Keeps the current value |
| `--per-day <usd>`      | Sets the UTC-day spending maximum.                     | Keeps the current value |
| `--ceiling <usd\|off>` | Sets or disables the automatic Base USDC ceiling.      | Keeps the current value |

```bash
vapi accounts caps researcher --per-call 0.05 --per-day 1 --ceiling 5
```

### `vapi send <amount>`

Moves USDC to the owner or another active owner account through the gas-paid relay

| Option                       | What it does                                           | Default           |
| ---------------------------- | ------------------------------------------------------ | ----------------- |
| `--from <account>`           | Selects the sending account. Required.                 | None              |
| `--to <account\|owner\|0x…>` | Selects the recipient. Required.                       | None              |
| `--network <base\|arc>`      | Selects the transfer network.                          | `base`            |
| `--resume <nonce>`           | Reuses an authorization after an unknown relay result. | Starts a transfer |

```bash
vapi send 2 --from research --to writer
```

### `vapi accounts distribute`

Plans, journals, and runs a multi-account distribution

| Option                       | What it does                                                                                                 | Default                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| `<amount>`                   | Sets the total USDC amount to distribute.                                                                    | Required for a new plan            |
| `--from <account>`           | Selects the sender.                                                                                          | Required for a new plan            |
| `--to <a,b,c>`               | Selects local linked active recipients.                                                                      | Every other eligible local account |
| `--network <base\|arc>`      | Selects the transfer network.                                                                                | `base`                             |
| `--resume <movement-id>`     | Continues unfinished legs with their recorded nonces.                                                        | Starts a plan                      |
| `--cancel <movement-id>`     | Cancels eligible unsent legs without signing. Terminal only and unavailable through MCP.                     | Not applicable                     |
| `--replace-expired-restored` | Allows reviewed restored legs to be replaced or cancelled. Requires `--resume` or `--cancel`; terminal only. | Refuses unproven restored legs     |
| `--bind-legacy-addresses`    | Binds reviewed addresses on an unsigned pre-0.8 leg. Requires `--resume`; terminal only.                     | Refuses an unbound legacy leg      |

```bash
vapi accounts distribute 10 --from main --to research,writer
vapi accounts distribute --resume <movement-id>
vapi accounts distribute --cancel <movement-id>
```

The `--cancel`, `--replace-expired-restored`, and `--bind-legacy-addresses` forms require the 0.8.0 preview.

## Legacy wallet aliases

The `vapi wallet` commands are compatibility aliases for account commands. Use `vapi accounts` and `--account <name>` in new scripts.

| Legacy command                   | Current command                      |
| -------------------------------- | ------------------------------------ |
| `vapi wallet list`               | `vapi accounts`                      |
| `vapi wallet create <name>`      | `vapi accounts add <name> --no-link` |
| `vapi wallet use <name>`         | `vapi accounts use <name>`           |
| `vapi wallet rename <old> <new>` | `vapi accounts rename <old> <new>`   |
| `vapi wallet remove <name>`      | `vapi accounts remove <name>`        |
| `vapi wallet restore <name>`     | `vapi accounts restore <name>`       |
| `vapi wallet caps <name>`        | `vapi accounts caps <name>`          |

### `vapi balance`

The selected account's address and USDC balances

| Option             | What it does                    | Default                                                  |
| ------------------ | ------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the account to inspect. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi balance --account main
```

## Discovery

### `vapi search [query]`

Searches the registry's marketplace discovery feed, including mirrored external listings

| Option                 | What it does                                                                               | Default                  |
| ---------------------- | ------------------------------------------------------------------------------------------ | ------------------------ |
| `--kind <kind>`        | Filters by kind and can be repeated.                                                       | Not stated in the README |
| `--network <caip2>`    | Filters by CAIP-2 network identifier.                                                      | Not stated in the README |
| `--limit <n>`          | Limits the number of results.                                                              | Not stated in the README |
| `--cursor <cursor>`    | Continues from a discovery cursor.                                                         | Not stated in the README |
| `--include-unverified` | Includes self-listed APIs that passed the automated x402 probe but have not been reviewed. | Excluded                 |

```bash
vapi search "weather" --include-unverified
```

### `vapi inspect <id>`

Verification, fee, liveness, conformance, identity, contract and live quote, for free

| Option              | What it does                        | Default                  |
| ------------------- | ----------------------------------- | ------------------------ |
| `--endpoint <name>` | Selects an endpoint on the listing. | Not stated in the README |

```bash
vapi inspect weather-call --endpoint forecast
```

### `vapi check <url>`

Grades its 402, extensions and same-origin discovery. Never pays

| Option              | What it does                                | Default                  |
| ------------------- | ------------------------------------------- | ------------------------ |
| `--method <method>` | Sends the check with the given HTTP method. | Not stated in the README |

```bash
vapi check https://weather.example/forecast --method GET
```

## Paying

### `vapi pay <id-or-url>`

Calls the API and pays it from the local wallet, naming an unverified tier

| Option                        | What it does                                                           | Default                                                  |
| ----------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| `--method <method>`           | Sets the HTTP method for the request.                                  | Not stated in the README                                 |
| `--endpoint <name>`           | Selects an endpoint on the listing.                                    | Not stated in the README                                 |
| `--body <json>`               | Sends a JSON request body.                                             | Not stated in the README                                 |
| `--content-type <type>`       | Sets the request content type.                                         | Not stated in the README                                 |
| `--network <caip2>`           | Selects the payment network.                                           | Not stated in the README                                 |
| `--expected-pay-to <address>` | Checks the expected payment recipient.                                 | Not stated in the README                                 |
| `--max <amount>`              | Sets the maximum for this call in US dollars.                          | Not stated in the README                                 |
| `--max-price-usd`             | Acts as a long-standing alias for `--max`; the two cannot be combined. | Not stated in the README                                 |
| `--account <name>`            | Selects the wallet that pays.                                          | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi pay weather-call --endpoint forecast --max 0.02 --account main
```

Every payment payload carries the client code `vapi` in the x402 `builder-code` extension. When the API advertises `payment-identifier`, vAPI generates one ID, sends it with the payment, records it as `paymentId` on the receipt, and shows it again in `vapi pay --resume`.

### `vapi pay --resume <receipt-id>`

Checks settlement, shows its payment id, and never pays

This command has no command-specific options.

```bash
vapi pay --resume receipt-123
```

This command asks the token contract on the receipt's network whether the signed EIP-3009 authorization was used. Settled means the payment went through, so do not pay again. Expired means it was never used and can no longer be used, so paying again is safe. Pending means it is unused but still valid, so wait until the printed time. The command unlocks no wallet and signs nothing. It supports EVM receipts; a Solana receipt or a receipt from before 0.4.0 says why it cannot check.

## Receipts and stats

### `vapi receipts`

The local append-only call ledger, newest last

| Option             | What it does                         | Default                                                  |
| ------------------ | ------------------------------------ | -------------------------------------------------------- |
| `--limit <n>`      | Limits the number of receipts.       | Not stated in the README                                 |
| `--account <name>` | Selects the wallet's receipts.       | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--all-wallets`    | Includes receipts from every wallet. | Not stated in the README                                 |

```bash
vapi receipts --account main --limit 20
```

### `vapi receipts export`

Raw receipts for a spreadsheet or dashboard

| Option                   | What it does                         | Default                                                  |
| ------------------------ | ------------------------------------ | -------------------------------------------------------- |
| `--format <json\|csv>`   | Selects JSON or CSV output.          | Not stated in the README                                 |
| `--range <24h\|7d\|30d>` | Selects the time range.              | Not stated in the README                                 |
| `--account <name>`       | Selects the wallet's receipts.       | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--all-wallets`          | Includes receipts from every wallet. | Not stated in the README                                 |

```bash
vapi receipts export --format csv --range 7d --account main
```

### `vapi stats`

Spend, outcomes, latency percentiles and top services

| Option                   | What it does                      | Default                                                  |
| ------------------------ | --------------------------------- | -------------------------------------------------------- |
| `--range <24h\|7d\|30d>` | Selects the time range.           | Not stated in the README                                 |
| `--account <name>`       | Selects the wallet's stats.       | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--all-wallets`          | Includes stats from every wallet. | Not stated in the README                                 |

```bash
vapi stats --range 24h --account main
```

## Agents

Agents hold rights on your account, never on your wallet. See [Agents](https://docs.vapinetwork.ai/agents/).

### `vapi login`

Links the local agent wallet to your vAPI account

| Option             | What it does                                       | Default                                                  |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the local agent wallet to link.            | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--label <name>`   | Sets the agent label shown to the owner.           | Not stated in the README                                 |
| `--publish`        | Requests permission to publish on vAPI Call.       | Not requested                                            |
| `--no-browser`     | Prints the approval URL without opening a browser. | Browser opens on a terminal                              |

```bash
vapi login --account agent --label researcher
```

### `vapi logout`

Removes the selected wallet's agent link and stored credentials

| Option             | What it does                   | Default                                                  |
| ------------------ | ------------------------------ | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet to log out. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi logout --account agent
```

### `vapi whoami`

Shows the chosen wallet's owner link and permissions, whether the link is live, and its ERC-8004 agent identity.

| Option             | What it does                    | Default                                                  |
| ------------------ | ------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet to identify. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi whoami --account agent
```

### `vapi agent create <name>`

Creates a capped local agent wallet, profile and owner link

The instructions file can contain at most 20,000 characters.

| Option                  | What it does                                                     | Default                |
| ----------------------- | ---------------------------------------------------------------- | ---------------------- |
| `--model <id>`          | Selects the vAPI Router model.                                   | Required               |
| `--instructions <file>` | Reads the agent instructions from a file.                        | Required               |
| `--call-budget <usd>`   | Sets the wallet's daily spend cap.                               | `$1`                   |
| `--max-per-call <usd>`  | Sets the maximum for one paid call.                              | `$0.05`                |
| `--router-budget <usd>` | Suggests the agent's daily Compute allowance for owner approval. | `$1`                   |
| `--approve-above <usd>` | Asks for approval above this price.                              | `$0.50`                |
| `--include-unverified`  | Allows unverified listings.                                      | Verified listings only |
| `--max-steps <n>`       | Sets the maximum number of model steps.                          | `12`                   |

```bash
vapi agent create researcher --model <id> --instructions ./researcher.md
```

### `vapi agent run`

Runs the named agent in 0.7.0. The additional options and headless form require the 0.8.0 preview.

| Option                    | What it does                                                                         | Default                             |
| ------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------- |
| `--budget <usd>`          | Sets one hard limit across Call payments and Router top-ups.                         | The account's remaining per-day cap |
| `--detach`                | Starts the run in the local background runtime.                                      | Runs attached                       |
| `--runtime local`         | Selects the local background runtime. Requires `--detach`.                           | `local`                             |
| `--result-file <path>`    | Writes the final JSON result. Cannot be combined with `--detach`.                    | Does not write a result file        |
| `--bundle-env <VAR>`      | Selects the separate headless form and runs one bundled member in an ephemeral home. | Normal named-account form           |
| `--task-base64url <text>` | Supplies the headless task as base64url text. Requires `--bundle-env`.               | Direct task argument                |

```bash
vapi agent run researcher "Compare today's weather forecasts"
vapi agent run researcher "Compare today's weather forecasts" --budget 0.50
vapi agent run researcher "Compare today's weather forecasts" --detach
vapi agent run --bundle-env <VAR> "<task>" --result-file <path>
```

### `vapi agent list`

Lists profiles, links and today's Call and Router budgets

This command has no command-specific options.

```bash
vapi agent list
```

### `vapi agent pause <name>`

Stops future runs until the agent is resumed

This command has no command-specific options.

```bash
vapi agent pause researcher
```

### `vapi agent resume <name>`

Allows a paused agent to run again

This command has no command-specific options.

```bash
vapi agent resume researcher
```

### `vapi agent revoke <name>`

Revokes the link and removes the profile, but keeps its wallet

This command has no command-specific options.

```bash
vapi agent revoke researcher
```

## Swarms

See [Swarms](https://docs.vapinetwork.ai/agents/control/swarms) for the treasury and member model.

Every swarm command requires the 0.8.0 preview.

### `vapi swarm create <name>`

Creates or resumes a treasury, members, caps, profiles, links, and optional funding

| Option                                | What it does                                                                        | Default                  |
| ------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------ |
| `--agents <n>`                        | Creates the requested number of generated roles. Cannot be combined with `--roles`. | Two members              |
| `--roles <a,b,c>`                     | Sets ordered member roles. Cannot be combined with `--agents`.                      | Generated roles          |
| `--fund <usd>`                        | Funds the treasury during setup. Requires `--from`.                                 | No funding transfer      |
| `--from <account>`                    | Selects the linked funding account. Requires `--fund`.                              | None                     |
| `--strategy <targets\|even\|weights>` | Selects the allocation strategy.                                                    | `targets`                |
| `--targets <role=usd,...>`            | Sets role targets for the targets strategy.                                         | Strategy defaults        |
| `--caps <perCall>/<perDay>`           | Sets member caps.                                                                   | `$0.10/$1`               |
| `--treasury-caps <perCall>/<perDay>`  | Sets treasury movement caps.                                                        | `$5/$20`                 |
| `--network <base\|arc>`               | Sets the swarm network.                                                             | `base`                   |
| `--model <id>`                        | Sets the model for new member profiles.                                             | `venice/claude-sonnet-5` |
| `--no-wait`                           | Returns without waiting for owner link approvals.                                   | Waits for approvals      |

```bash
vapi swarm create research --roles lead,helper --fund 5 --from main
```

### `vapi swarm add|remove|fund|rebalance|status|dissolve`

Manages swarm membership and capital

| Command                                                  | What it does                                                                  |
| -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `vapi swarm add <name> <role>`                           | Adds or resumes one member.                                                   |
| `vapi swarm remove <name> <member>`                      | Sweeps a member to the treasury and removes its membership.                   |
| `vapi swarm fund <name> <usd> [--from <account>]`        | Funds the treasury or prints owner funding instructions.                      |
| `vapi swarm rebalance <name> [--targets <role=usd,...>]` | Moves funds between the treasury and members.                                 |
| `vapi swarm status <name>`                               | Shows balances, links, allocation history, open movements, and detached runs. |
| `vapi swarm dissolve <name>`                             | Sweeps capital and removes the swarm file.                                    |

```bash
vapi swarm add research helper
vapi swarm remove research helper
vapi swarm fund research 5 --from main
vapi swarm rebalance research --targets lead=2,helper=1
vapi swarm status research
vapi swarm dissolve research
```

### `vapi swarm run <name> "<task>"`

Runs the lead or each eligible member

| Option                     | What it does                                                               | Default                      |
| -------------------------- | -------------------------------------------------------------------------- | ---------------------------- |
| `--mode <lead\|each>`      | Runs the lead or every eligible member independently.                      | `lead`                       |
| `--lead <member>`          | Selects the lead account in lead mode.                                     | Swarm lead                   |
| `--budget <usd>`           | Sets each member's hard Call-and-Router budget.                            | Remaining per-day cap        |
| `--draw <usd>`             | Sets the shared treasury draw limit.                                       | `$2.00`                      |
| `--detach`                 | Starts background work.                                                    | Runs attached                |
| `--runtime local\|railway` | Selects the execution runtime.                                             | `local`                      |
| `--result-file <path>`     | Writes the attached final JSON result. Cannot be combined with `--detach`. | Does not write a result file |

```bash
vapi swarm run research "Compare three weather APIs" --mode each --budget 0.50
```

### `vapi swarm runs|stop`

Lists or stops detached work

| Command or option                | What it does                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `vapi swarm runs <name>`         | Lists stored run status for the swarm.                                                                             |
| `vapi swarm stop <name> <runId>` | Stops the specified run.                                                                                           |
| `vapi swarm stop <name> --all`   | Stops every run and tracked sandbox for the swarm.                                                                 |
| `--confirm-worker-stopped`       | Clears a stale id-less start after the owner proves the worker is gone. Terminal only and unavailable through MCP. |

```bash
vapi swarm runs research
vapi swarm stop research <runId>
vapi swarm stop research --all
```

## Router and Stake

See [vAPI Router](https://docs.vapinetwork.ai/router) and [vAPI Stake](https://docs.vapinetwork.ai/stake).

### `vapi router models`

Lists the vAPI Router model ids

| Option             | What it does               | Default                                                  |
| ------------------ | -------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the linked wallet. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi router models --account agent
```

### `vapi router usage`

Shows the agent's Compute allowance and Router balance

| Option             | What it does               | Default                                                  |
| ------------------ | -------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the linked wallet. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi router usage --account agent
```

### `vapi router chat --model <id> "<prompt>"`

Sends one chat request through vAPI Router

| Option             | What it does                         | Default                                                  |
| ------------------ | ------------------------------------ | -------------------------------------------------------- |
| `--system <text>`  | Sets the system message.             | Not stated in the README                                 |
| `--max-tokens <n>` | Sets the maximum output token count. | Not stated in the README                                 |
| `--account <name>` | Selects the linked wallet.           | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi router chat --model <id> "Summarize this API" --account agent
```

### `vapi router key`

Prints a gated Router key or rotates it without printing it

| Option             | What it does                                | Default                                                  |
| ------------------ | ------------------------------------------- | -------------------------------------------------------- |
| `--rotate`         | Rotates the Router key without printing it. | Prints the current gated key                             |
| `--account <name>` | Selects the linked wallet.                  | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi router key --rotate --account agent
```

### `vapi router buy <1|5|20|50>`

Buys vAPI Router balance with USDC from your wallet

| Option             | What it does                     | Default                                                  |
| ------------------ | -------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet that pays.    | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--json`           | Writes one JSON value to stdout. | Human-readable terminal output                           |

```bash
vapi router buy 5 --account agent
```

### `vapi router buy --auto <1|5|20|50> --below <usd>`

Sets or clears automatic vAPI Router balance refill

| Option             | What it does                              | Default                                                  |
| ------------------ | ----------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet that pays for refills. | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--auto off`       | Clears automatic refill.                  | Not applicable                                           |

```bash
vapi router buy --auto 5 --below 2.50 --account agent
vapi router buy --auto off --account agent
```

### `vapi stake status`

Shows the linked owner's stake and Compute today

| Option             | What it does               | Default                                                  |
| ------------------ | -------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the linked wallet. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi stake status --account agent
```

### `vapi stake open`

Prints and optionally opens the staking page

| Option             | What it does                                       | Default                                                  |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the linked wallet.                         | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--no-browser`     | Prints the staking page without opening a browser. | Browser opens on a terminal                              |

```bash
vapi stake open --account agent
```

## Publishing

### `vapi publish <url>`

Probes your API, lists the endpoints you pick, signs the payout wallet

| Option                                           | What it does                                                                   | Default                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `--method <method>`                              | Sets the method for an endpoint probe.                                         | Not stated in the README                                 |
| `--mode <origin\|endpoint\|openapi>`             | Tells the registry whether the URL is an origin, endpoint or OpenAPI document. | Not stated in the README                                 |
| `--name <text>`                                  | Sets the listing name.                                                         | Not stated in the README                                 |
| `--description <text>`                           | Sets the listing description.                                                  | Not stated in the README                                 |
| `--category <ai\|data\|crypto\|compute\|search>` | Sets the listing category.                                                     | Not stated in the README                                 |
| `--select <names>`                               | Selects the endpoint names to list.                                            | Not stated in the README                                 |
| `--account <name>`                               | Selects the payout wallet that signs.                                          | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--yes`                                          | Takes all discovered endpoints without an interactive selection.               | Not stated in the README                                 |
| `--resume`                                       | Skips endpoints this API key already lists and publishes the rest.             | Not stated in the README                                 |

```bash
vapi publish https://weather.example --mode origin --name Weather --category data --yes --account provider
```

### `vapi publish activate <slug>`

Takes a listing live once its FeeSplitter is deployed

This command has no command-specific options.

```bash
vapi publish activate weather-call
```

### `vapi publish verify-request <slug>`

Asks vAPI to review the listing

This command has no command-specific options.

```bash
vapi publish verify-request weather-call
```

### `vapi publish list`

Every listing this API key owns

This command has no command-specific options.

```bash
vapi publish list
```

### `vapi claim <origin>`

Takes over the listings vAPI indexed from your API, signed by their payee

| Option             | What it does                                   | Default                                                  |
| ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the payee wallet that signs the claim. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi claim https://weather.example --account provider
```

## Auth

### `vapi auth set-key`

Types the registry API key on a prompt into the OS secret store

This command has no command-specific options.

```bash
vapi auth set-key
```

### `vapi auth status`

Whether this machine has a key and where it comes from, masked

This command has no command-specific options.

```bash
vapi auth status
```

### `vapi auth clear`

Takes the stored key back out

This command has no command-specific options.

```bash
vapi auth clear
```

## Maintenance

### `vapi sweep [<address>]`

Moves USDC to an address, or to the linked owner when omitted

| Option              | What it does                       | Default                                                  |
| ------------------- | ---------------------------------- | -------------------------------------------------------- |
| `--network <caip2>` | Selects the network for the sweep. | Every configured network                                 |
| `--account <name>`  | Selects the account to sweep.      | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi sweep --network eip155:8453 --account agent
```

### `vapi export-key`

Prints the private key. Terminal only, never for an agent.

| Option              | What it does                        | Default                                                  |
| ------------------- | ----------------------------------- | -------------------------------------------------------- |
| `--network <caip2>` | Selects the account network.        | Not stated in the README                                 |
| `--account <name>`  | Selects the account to export from. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi export-key --network eip155:8453 --account main
```

### `vapi backup`

Prints the vault recovery phrase or manages owner-encrypted cloud backup

| Option             | What it does                                                               | Default                                                  |
| ------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects a derived account before printing the vault phrase.                | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--cloud`          | Enrolls the device and uploads an encrypted backup after console approval. | Prints the recovery phrase                               |
| `--cloud off`      | Deletes the local backup key and stops later uploads.                      | Not applicable                                           |

```bash
vapi backup --account main
vapi backup --cloud
```

Phrase output is terminal-only and unavailable to agents. Cloud backup never returns the phrase or a private key.

### `vapi restore`

Restores a vault from a phrase or an owner-approved cloud backup

| Option          | What it does                                                                     | Default                                   |
| --------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
| `--from-owner`  | Starts owner-approved cloud restore on a new device.                             | Reads a recovery phrase                   |
| `--owner <0x…>` | Checks the expected owner before writing the vault. Required without a terminal. | Confirms the returned owner interactively |

```bash
vapi restore
vapi restore --from-owner --owner <0x…>
```

### `vapi import`

Restores a wallet from a prompt, never from argv

| Option                  | What it does                                                                             | Default                           |
| ----------------------- | ---------------------------------------------------------------------------------------- | --------------------------------- |
| `--phrase`              | Imports from recovery words entered at a prompt.                                         | Not stated in the README          |
| `--key`                 | Imports from a private key entered at a prompt.                                          | Not stated in the README          |
| `--account <name>`      | Names the new wallet.                                                                    | `main` only when no wallet exists |
| `--networks <base,arc>` | Selects the networks for the restored wallet. Device-vault imports support Base and Arc. | Not stated in the README          |
| `--replace`             | Moves vault account metadata or a legacy encrypted keystore to trash before replacement. | Not stated in the README          |
| `--force`               | Allows replacement when the named wallet still holds USDC on Base.                       | Not stated in the README          |

```bash
vapi import --phrase --account backup-2026 --networks base,arc
```

### `vapi passphrase`

Changes a legacy keystore's passphrase. Protect current vault accounts with `vapi vault protect`.

| Option             | What it does                                 | Default                                                  |
| ------------------ | -------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet whose passphrase changes. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi passphrase --account main
```

### `vapi vault protect|unprotect|lock|unlock|status`

Manages password protection and the device-wide vault session

| Command                | What it does                                              |
| ---------------------- | --------------------------------------------------------- |
| `vapi vault protect`   | Adds password protection to the device vault.             |
| `vapi vault unprotect` | Removes password protection from the device vault.        |
| `vapi vault unlock`    | Opens the protected vault on this device for eight hours. |
| `vapi vault lock`      | Ends the protected vault session.                         |
| `vapi vault status`    | Shows the vault protection and session state.             |

```bash
vapi vault protect
vapi vault unprotect
vapi vault lock
vapi vault status
vapi vault unlock
```

Set `VAPI_VAULT_PASSWORD` for unattended protected-vault access.

### `vapi unlock`

This deprecated alias routes current vault accounts to `vapi vault unlock` for an eight-hour device-wide session. Legacy accounts store their passphrase in the OS secret store.

| Option             | What it does                | Default                                                  |
| ------------------ | --------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet to open. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi unlock --account agent
```

### `vapi lock`

This deprecated alias routes current vault accounts to `vapi vault lock`. Legacy accounts have their stored passphrases removed.

| Option             | What it does                                                                | Default                                                  |
| ------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet to lock.                                                 | `VAPI_WALLET`, then the default from `vapi accounts use` |
| `--all`            | Locks the vault session and removes every stored legacy account passphrase. | Not stated in the README                                 |

```bash
vapi lock --all
```

### `vapi report "<what>"`

Writes a privacy-preserving local bug report

| Option                | What it does                             | Default                  |
| --------------------- | ---------------------------------------- | ------------------------ |
| `--include-addresses` | Includes wallet addresses in the report. | Not stated in the README |
| `--send`              | Sends the report.                        | Not stated in the README |

```bash
vapi report "search returned no listings"
```

### `vapi mcp`

Serves the MCP tools over stdio

| Option             | What it does                               | Default                                                  |
| ------------------ | ------------------------------------------ | -------------------------------------------------------- |
| `--account <name>` | Selects the wallet used by the MCP server. | `VAPI_WALLET`, then the default from `vapi accounts use` |

```bash
vapi mcp --account agent
```

### `vapi mcp install <claude|cursor|codex>`

Writes an MCP server entry for the selected client and prints the file it changed

| Option             | What it does                                    | Default                                                            |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------ |
| `--home <dir>`     | Sets `VAPI_HOME` for the installed server.      | `VAPI_HOME`, then `~/.vapi`                                        |
| `--registry <url>` | Sets the registry URL for the installed server. | The selected home's configured registry, then the default registry |

```bash
vapi mcp install codex --home /srv/vapi --registry https://registry.example
```

Cursor uses `.cursor/mcp.json` in the current directory. Codex uses `~/.codex/config.toml`. Claude uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `~/.config/Claude/claude_desktop_config.json` on Linux, and `%APPDATA%/Claude/claude_desktop_config.json` on Windows.

### `vapi serve`

Preview only; exits `2` with a message

This command has no command-specific options.

```bash
vapi serve
```

### `vapi version`

The client version, also as `--version` or `-v`

This command has no command-specific options.

```bash
vapi version
```

### `vapi help`

Prints command usage, also as `--help` or `-h`. Bare `vapi` shows device status.

This command has no command-specific options.

```bash
vapi help
```

## Configuration and environment variables

Local state lives in `~/.vapi/`. `VAPI_HOME` can select another directory.

| Variable                                                                                    | What it does                                                                 |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `VAPI_HOME`                                                                                 | Uses a different directory instead of `~/.vapi`.                             |
| `VAPI_WALLET`                                                                               | Selects the wallet when no `--account` is given.                             |
| `VAPI_REGISTRY_URL`                                                                         | Replaces the registry base; the canonical discovery paths derive from it.    |
| `VAPI_DISCOVERY_URL`                                                                        | Sets the services discovery URL.                                             |
| `VAPI_MARKETPLACE_DISCOVERY_URL`                                                            | Sets the marketplace discovery URL.                                          |
| `VAPI_VAULT_PASSWORD`                                                                       | Supplies the device-vault password.                                          |
| `VAPI_KEYSTORE_PASSWORD`                                                                    | Supplies a legacy keystore password and remains a deprecated vault fallback. |
| `VAPI_API_KEY`                                                                              | Supplies the registry key that `vapi publish` authenticates with in CI.      |
| `VAPI_NO_SECRETS`                                                                           | Set to `1` to stop `vapi backup` and `vapi export-key` printing anything.    |
| `BASE_RPC_URL`                                                                              | Overrides the Base RPC.                                                      |
| `ARC_RPC_URL`                                                                               | Overrides the Arc mainnet RPC.                                               |
| `ARC_TESTNET_RPC_URL`                                                                       | Sets the Arc testnet RPC endpoint.                                           |
| `VAPI_ARC_GAS_HEADROOM_USDC`                                                                | Sets the USDC retained for Arc sweep gas.                                    |
| `VAPI_DEVICE`                                                                               | Overrides the device name.                                                   |
| `CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `OPENAI_CODEX`, `AGENT`, `CI` | Mark an agent or CI environment where secret exports are refused.            |

`ARC_RPC_URL` also enables Arc mainnet.

Current accounts live in `vault.json`, with account metadata in `wallets.json` and the device key in the OS secret store. Other local files include `config.json`, `audit.log`, `receipts.jsonl`, `searches.jsonl`, `spend-ledger.json`, and `reports/`. Removed vault accounts leave metadata-only trash records. Legacy accounts use individual encrypted keystores, and removed legacy accounts move those files to trash.

## Next

* [Open source](/reference/open-source.md)
* [SDK](/reference/sdk.md)
* [Run your first agent](https://docs.vapinetwork.ai/agents/quickstart)

Checked on 2026-10-02.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vapinetwork.ai/reference/cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.