Command Reference

Complete reference for all Vault CLI and Console commands.

Running Vault

This reference covers Vault Terminal (pip install primer-vault) and Vault Desktop's File → Console panel, which share the same commands. There are no mode flags — primer-vault behaves the same wherever it runs:

# Open a session: a prompt plus a live event feed
primer-vault

# Run one command and exit
primer-vault agent list

# Run at boot, unattended
primer-vault install-service

Whether a given primer-vault process is the engine or attaches to one already running against the same data directory is decided automatically by the instance lock — there is nothing to choose. Closing the terminal that started a session never stops an engine you did not start; only the process that first created it does, or an explicit shutdown command.

Flags (single-command mode)

A password given on the command line is not private. It is visible to every other user on the machine in the process list, and your shell usually keeps it in history. For unattended use set PRIMER_VAULT_PASSWORD instead, which is neither.

Environment

Running Unattended

Register Vault with the OS service manager so it starts at boot and stays up:

primer-vault install-service

Registers with systemd on Linux or Task Scheduler on Windows. On Linux, put PRIMER_VAULT_PASSWORD=... in /etc/primer-vault.env and uncomment the EnvironmentFile= line in the generated unit; on Windows, set it as a system environment variable. Also set startup-wallet and start-agent-api so the service actually opens a wallet and serves agents once it starts, rather than coming back up idle after a reboot:

config set startup-wallet main
config set start-agent-api on

Multiple Sessions

Every primer-vault invocation is independent, but they all reach the same engine once one exists. Start a long-running session once, then drive it from as many terminals as you like:

# First terminal: start the engine and keep it open
PRIMER_VAULT_PASSWORD="secret" primer-vault
> wallet open mywallet
> server start

# A second terminal attaches to the same engine automatically
primer-vault seed list
primer-vault agent register "My Bot"

No flag makes this work — a second primer-vault against a data directory that already has an engine running always attaches to it, over the local control channel, rather than being refused or starting a rival.

Basic Commands

Wallet Commands

Manage the encrypted wallet file.

wallet status

Show wallet lock state and address count.

wallet create <name>

Create a new wallet file. A password is required (8-character minimum) — it is what encrypts your keys, so choose a long passphrase. Vault cannot create an unencrypted wallet.

wallet create mywallet

On success, displays the 12-word recovery phrase. Back this up securely!

wallet open [name]

Open and unlock a wallet file.

wallet open mywallet

wallet lock

Lock the wallet, clearing sensitive data from memory.

wallet detach

Unload the wallet without deleting the file. Useful for switching wallets.

wallet delete

Delete the current wallet file. Requires confirmation.

Seed Commands

Manage HD wallet seeds (BIP-39 mnemonic phrases). Requires unlocked wallet.

seed list

List all seeds in the wallet.

seed create [--words 12|24]

Create a new seed with a randomly generated mnemonic.

seed create
seed create --words 24

seed import [phrase]

Import an existing BIP-39 mnemonic phrase.

seed import "abandon abandon abandon ... about"

seed delete <seed>

Delete a seed and all its derived addresses.

seed delete S002

Requires YES confirmation. Agents using affected addresses will be decommissioned.

Address Commands

Manage wallet addresses. Requires unlocked wallet.

address list

List all addresses in the wallet.

address create [seed] [index] [name]

Derive a new address from an existing seed.

# Derive next address from first seed
address create

# Derive from specific seed at index 5
address create S001 5

# Derive with custom name
address create S001 3 "My Agent Address"

address import <key> [name]

Import a private key directly (not derived from seed).

address import 0xabc123... "Imported Key"

address rename <address> <name>

Rename an address.

address rename A001 "Primary Funding"

address delete <address>

Delete an address from the wallet.

address delete A002

Agents using this address will be decommissioned.

address export <address>

Export the private key for an address.

address export A001

Requires YES confirmation. Handle private keys with extreme care!

address balance [address]

Check on-chain balance via Blockscout API. Shows all tokens held.

# Check all addresses
address balance

# Check specific address
address balance A001

address ledger list

Read addresses off a connected Ledger device, so you can see what is on it before deciding what to enrol. Available in both editions — the terminal prints the same information the desktop's paged picker shows.

address ledger add <index> [name]

Enrol the address at a derivation index, so signing and lending can use it.

address ledger add 0 "Ledger Main"

address ledger verify <address>

Re-derive a stored address on the connected device and confirm it matches, before funding it.

address ledger verify A003

Agent Commands

Register and manage AI agents that can request payment signatures and execute trades.

agent list

List all registered agents.

agent show <agent>

Display detailed agent information.

agent show my-agent
agent show ABC123

agent register <name> [--auth hmac|bearer]

Register a new agent.

agent register my-claude-agent
agent register api-bot --auth bearer

Returns environment variables for agent configuration:

PRIMER_VAULT_AGENT_ID=ABC123
PRIMER_VAULT_AGENT_TOKEN=AT_...
PRIMER_VAULT_AUTH_MODE=hmac
PRIMER_VAULT_URL=http://localhost:4663

agent commission <agent> <policy> <address> [--mandate] [--upload]

Activate an agent with a policy and funding address.

agent commission my-agent standard A001
agent commission my-agent standard A001 --mandate --upload

agent edit <agent> [--policy P] [--address A]

Modify an agent's policy or address without full re-commissioning.

agent edit my-agent --policy strict
agent edit my-agent --address A002

agent instructions <agent> [--regenerate]

Display agent credentials and setup instructions.

agent instructions my-agent
agent instructions ABC123 --regenerate

For Bearer agents, use --regenerate to create a new token (invalidates the old one).

agent mandate <agent> [--upload]

Generate an Intent Mandate for a commissioned agent.

agent suspend <agent>

Temporarily suspend a commissioned agent.

agent activate <agent>

Re-enable a suspended agent.

agent delete <agent>

Delete an agent permanently.

Policy Commands

Create and manage spending policies that control agent behavior.

policy list

List all policies.

policy show <policy>

Display policy details.

policy create <name> [options]

Create a new spending and trading policy.

# Basic policy (payments only)
policy create standard

# Policy with custom payment limits
policy create premium --day 500 --txn 50 --auto 5

# Policy with trading enabled
policy create trader --day 100 --txn 10 --auto 1 \
  --trading --trade-daily 500 --trade-max 100 --trade-auto 25

# Strict policy requiring manual approval for all
policy create manual --day 1000 --auto 0 --trading --trade-auto 0

Payment Limits:

Trading Limits:

Morpho Lending Limits:

policy edit <policy> [options]

Modify an existing policy. Only specified options will be changed. Accepts the same payment, trading and lending amount options as policy create (--day, --trade-max, --morpho-max, and so on, unchanged). The three enable switches take an explicit value on edit instead of a bare flag: --x402 on|off, --trading on|off, --morpho on|off — and Morpho's venue restriction is --restrict on|off rather than the create-only --no-restrict.

# Increase payment limits
policy edit standard --day 200 --auto 10

# Enable trading on an existing policy
policy edit standard --trading on --trade-daily 250 --trade-auto 10

# Enable Morpho lending on an existing policy
policy edit standard --morpho on --morpho-max 50 --morpho-total 250

Enabling Morpho lending for the first time on a policy that has never had it seeds the same defaults policy create --morpho would.

policy delete <policy>

Delete a policy. Agents using this policy will be decommissioned.

Server Commands

Control the agent HTTP server.

server status

Show server status and port.

server start [port]

Start the agent server.

server start
server start 4665

Default port is 4663.

server stop

Stop the server.

Approval Commands

Manage pending payment, trade and lending requests that require manual approval.

pending

List pending approval requests across all three lanes — payments, trades and Morpho lending.

approve <id>

Approve a pending request.

approve req001

reject <id> [reason]

Reject a pending request with optional reason.

reject req001 "exceeds budget"

Trade Commands

Manage pending agent trades.

trade pending

List pending trade requests.

trade approve <id>

Approve a pending trade.

trade reject <id> [reason]

Reject a pending trade.

Position Commands

Manage pending Morpho lending requests, and see what venues an agent's policy permits.

position pending

List pending lending requests (supply or withdraw).

position approve <id>

Approve a pending lending request. Re-quotes and re-checks policy against the current state before executing, the same way trade approve does.

position reject <id> [reason]

Reject a pending lending request.

venues

List the Morpho venues an agent's policy permits, and what it currently holds in each. Matches what POST /venues returns to the agent itself.

History Commands

View transaction history (payments and trades).

history [limit]

List recent transactions.

history
history 50

history show <tx_id>

Display detailed transaction information.

history show tx001abc

history export [filename]

Export transactions to CSV file.

history export
history export ~/payments.csv

history verify <tx_id>

Verify a transaction exists on-chain.

history receipt <tx_id>

Get AP2-formatted receipt for a transaction.

history clear

Clear all transaction history. Requires confirmation.

Config Commands

Manage application settings.

config show

Display all current settings.

config get <setting>

Get a specific setting value.

config get verify-settlements
config get network 4663

config set <setting> <value>

Set a configuration value.

Available Settings

config set verify-settlements on
config set network 4663 on
config set rpc 4663 https://my-custom-rpc.com

Common Workflows

Initial Setup

# 1. Create a wallet
wallet create mywallet

# 2. Create a spending policy
policy create standard --day 100 --txn 10 --auto 1

# 3. Register an agent
agent register my-ai-agent --auth bearer

# 4. Commission the agent
agent commission my-ai-agent standard A001

# 5. Start the server
server start

Importing an Existing Seed

# 1. Create empty wallet
wallet create recovery-wallet

# 2. Import your seed phrase
seed import "your twelve word phrase here ..."

# 3. Derive addresses
address create S002 0 "Primary"
address create S002 1 "Secondary"

Managing Multiple Agents

# Different policies for different trust levels
policy create low-trust --day 10 --txn 1 --auto 0
policy create high-trust --day 1000 --txn 100 --auto 50

# Register and commission agents
agent register untrusted-bot
agent commission untrusted-bot low-trust A001

agent register trusted-bot
agent commission trusted-bot high-trust A002

Exit Codes