Command Reference

Complete reference for all Vault CLI and Console commands.

Running Vault

# GUI mode (default)
primer-vault

# CLI interactive REPL
primer-vault --cli

# CLI single command
primer-vault --cli agent list

# Headless daemon
primer-vault --headless

Daemon Options

Multi-Command Automation (Daemon Pattern)

Each CLI invocation is a separate process. Wallet unlock state does not persist between invocations. For multi-step automation, use the headless daemon:

# Start daemon and unlock wallet in one command
primer-vault --headless --wallet mywallet --password "secret"

# All subsequent CLI invocations connect to the running daemon
primer-vault --cli seed list
primer-vault --cli agent register "My Bot"
primer-vault --cli server start

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. You will be prompted for a password (optional).

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

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 XK7M2P

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=XK7M2P
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 XK7M2P --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:

policy edit <policy> [options]

Modify an existing policy. Only specified options will be changed. Accepts all payment and trading options from policy create.

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

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

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. Port 4664 is reserved for the admin API.

server stop

Stop the server.

Approval Commands

Manage pending payment and trade requests that require manual approval.

pending

List pending approval requests (payments and trades).

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.

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