Vultisig CLI

Command-line interface for Vultisig MPC wallet operations. See the router skill for an overview of MPC benefits and to choose between CLI and SDK.

Installation

npm install -g @vultisig/cli
vultisig --version

Or run without installing:

npx @vultisig/cli balance ethereum

Security Considerations

CRITICAL: Read before executing any commands

1. Never store passwords in scripts, logs, or environment variables visible to others
2. Use --password flag only in secure, ephemeral contexts
3. Always verify recipient addresses - transactions are irreversible
4. Export backups before destructive operations - use vultisig export
5. Use -o json for automation - structured output prevents parsing errors

Vault Types

Type	Threshold	Signing	Best For
FastVault	2-of-2 (device + server)	Instant, server-assisted	AI agents, automation, bots
SecureVault	N-of-M (configurable)	Multi-device coordination	Teams, high-value assets

For AI agents, FastVault is recommended - it enables instant signing without multi-device coordination.

See references/vault-types.md for detailed comparison including key shares explanation.

Understanding Vault Shares (MPC Key Shares)

Vultisig uses Multi-Party Computation (MPC) to split private keys into shares. No single party ever holds the complete private key.

FastVault (2-of-2):

• Share 1: Stored on your device, encrypted with your vault password (in a .vult file)
• Share 2: Stored on VultiServer
• Both shares must cooperate to sign a transaction. The server never sees your share, you never see theirs.
• Each share contains ECDSA, EdDSA, and ML-DSA (post-quantum) key material.

SecureVault (N-of-M):

• Shares are distributed across M devices (phones, laptops, etc.)
• Any N shares can cooperate to sign (e.g., 2-of-3 means any 2 of 3 devices)
• No server involved — coordination happens via a relay that never sees key material.

What to tell users: "Your vault uses threshold signing. Your private key is split into shares — no single device or server holds the full key. Signing requires cooperation between share holders."

See references/vault-types.md for full details on key shares.

Quick Start (Agent-Friendly, Non-Interactive)

FastVault creation requires email verification. Use --two-step for a fully non-interactive flow (or the CLI auto-detects non-TTY environments and enables it automatically).

1. Create a FastVault

vultisig create fast \
  --name "agent-wallet" \
  --email "[email protected]" \
  --password "SecurePass123!" \
  --two-step \
  -o json

Returns:

{
  "vaultId": "abc123-def456",
  "status": "pending_verification",
  "message": "Vault created. Verify with email OTP to activate.",
  "verifyCommand": "vultisig verify abc123-def456 --code <OTP>",
  "resendCommand": "vultisig verify abc123-def456 --resend --email [email protected] --password <password>"
}

2. Verify with Email OTP

The user receives a 4-6 digit code by email. Verify non-interactively:

vultisig verify abc123-def456 --code 123456 -o json

Returns:

{"verified": true, "vault": {"id": "abc123-def456", "name": "agent-wallet", "type": "fast"}}

To resend the verification email:

vultisig verify abc123-def456 --resend --email "[email protected]" --password "SecurePass123!"

3. Get Addresses

vultisig addresses -o json

4. Check Balance

vultisig balance ethereum -o json
vultisig balance --tokens -o json  # Include ERC-20 tokens

5. Send Transaction

vultisig send ethereum 0xRecipient... 0.1 --password "SecurePass123!" -y -o json

6. Swap Tokens

vultisig swap-quote ethereum bitcoin 0.1 -o json
vultisig swap ethereum bitcoin 0.1 --password "SecurePass123!" -y -o json

Core Commands

Vault Management

Command	Description
create fast --name --email --password [--two-step]	Create FastVault (server-assisted 2-of-2). Use --two-step for non-interactive mode
create secure --name --shares N	Create SecureVault (multi-device N-of-M)
verify <vaultId> --code <code>	Verify vault with email OTP (non-interactive)
verify <vaultId>	Verify vault (interactive prompt for code)
verify <vaultId> --resend --email <email> --password <pass>	Resend verification email
vaults -o json	List all vaults
switch <vaultId>	Switch active vault
info -o json	Show vault details (includes vault type, chains, addresses)
import <file.vult>	Import vault from backup
export [path]	Export vault backup
delete [vault] -y	Delete vault

Wallet Operations

Command	Description
addresses -o json	Get all addresses
balance [chain] -o json	Get balance (optional: specific chain)
balance --tokens -o json	Include token balances
portfolio -o json	Total portfolio value in fiat
portfolio --currency EUR -o json	Portfolio in specific currency
send <chain> <to> <amount>	Send native token
send <chain> <to> <amount> --token <addr>	Send ERC-20/SPL token

Swap Operations

Command	Description
swap-chains	List chains supporting swaps
swap-quote <from> <to> <amount>	Get swap quote
swap <from> <to> <amount>	Execute swap

Rujira / THORChain Secured Assets

Secured assets are L1 assets (BTC, ETH, etc.) deposited to THORChain, backed 1:1 on the native chain, and tradeable on THORChain's FIN DEX.

Command	Description
rujira balance -o json	Show secured asset balances on THORChain
rujira balance --secured-only -o json	Filter to secured/FIN denoms only
rujira routes -o json	List available FIN swap routes
rujira deposit --asset BTC.BTC --amount 100000	Get deposit instructions (inbound address + memo)
rujira swap --from-asset THOR.RUNE --to-asset ETH.ETH --amount 100 -y	Execute FIN swap
rujira withdraw --asset BTC.BTC --amount 100000 --l1-address bc1q... -y	Withdraw secured assets to L1

Asset naming: BTC.BTC, ETH.ETH, ETH.USDC-0xa0b8..., THOR.RUNE

See references/rujira.md for detailed Rujira/secured assets guide.

Chain & Token Management

Command	Description
chains	List active chains
chains --add Solana	Enable a chain
chains --add-all	Enable all 36+ chains
chains --remove Litecoin	Disable a chain
tokens <chain>	List tokens on chain
tokens <chain> --add <contract>	Add custom token

Agent Chat (AI-to-AI)

The agent ask command lets AI coding agents (Claude Code, Opencode, Cursor, etc.) talk to the Vultisig agent backend for natural-language crypto operations. The backend proposes tool calls; the CLI executor runs supported actions locally (balances, portfolio, builds, signing, and more). Unsupported actions return success: false from the CLI and may only be satisfied server-side.

Command	Description
agent ask "<message>"	Send a single message, get the response
agent ask "<message>" --session <id>	Continue an existing conversation
agent ask "<message>" --json	Output structured JSON
agent ask "<message>" --verbose	Show tool calls on stderr
agent sessions list	List chat sessions for the current vault
agent sessions delete <id>	Delete a session

Output Formats

Text (default):

session:conv_abc123

Your HYPE balance is 42.567 HYPE on Hyperliquid.

JSON (--json):

{"session_id":"conv_abc123","response":"Your HYPE balance is ...","tool_calls":[{"action":"get_balances","success":true}],"transactions":[]}

Transaction output (text):

session:conv_abc123

Sent 0.01567 HYPE to 0x...

tx:Hyperliquid:0xabc123...
explorer:https://hyperliquid.xyz/tx/0xabc123...

Multi-Turn Conversations

The first call returns a session ID on the first line of stdout. Pass it back with --session to continue the conversation:

# Turn 1: Ask a question
RESPONSE=$(vultisig agent ask "What is my HYPE balance?" --vault t1 --password 1)
SESSION=$(echo "$RESPONSE" | head -1 | cut -d: -f2-)

# Turn 2: Use the answer in a follow-up
vultisig agent ask "Send 0.01 HYPE to myself" --session "$SESSION" --vault t1 --password 1

With --json, extract the session ID from the JSON:

RESULT=$(vultisig agent ask "What is my ETH balance?" --vault t1 --password 1 --json)
SESSION=$(echo "$RESULT" | jq -r '.session_id')
vultisig agent ask "Send 0.001 ETH to 0x..." --session "$SESSION" --vault t1 --password 1 --json

How It Works

1. The CLI authenticates with the agent backend using the vault's MPC key (no extra API keys needed)
2. Your message is sent to the backend, which routes it to an AI model with MCP-style tools
3. For each tool call, the CLI executor runs it when implemented (e.g. get_balances, build_send_tx); otherwise it reports failure back to the backend
4. When a transaction is ready, the CLI signs and broadcasts locally using MPC (the server never sees the full key)
5. The result is streamed back and returned in the response

Notes

• No helper scripts needed — agent ask handles the full lifecycle (auth, streaming, tool execution, signing)
• Signing is local — transaction signing happens client-side via MPC; payloads may be built locally or supplied by the backend before signing
• Password is required for signing — use --password flag; the CLI will error if a signing operation is needed without it
• Backend URL defaults to https://abe.vultisig.com or the VULTISIG_AGENT_URL environment variable
• stdout is clean — all debug output, SDK logs, and MPC progress go to stderr; only the structured response goes to stdout

Advanced Operations

Command	Description
sign --chain <chain> --bytes <base64>	Sign pre-hashed bytes
broadcast --chain <chain> --raw-tx <hex>	Broadcast raw transaction

JSON Output Mode

Always use -o json for AI agent automation. This provides structured, parseable output:

# Balance (single chain)
vultisig balance ethereum -o json
# {"chain":"ethereum","balance":{"native":"1.5","symbol":"ETH","usdValue":"3750.00"}}

# Balance (all chains)
vultisig balance -o json
# {"balances":[{"chain":"ethereum","balance":{"native":"1.5","symbol":"ETH","usdValue":"3750.00"}},{"chain":"bitcoin","balance":{"native":"0.1","symbol":"BTC","usdValue":"6500.00"}}]}

# Portfolio (total fiat value)
vultisig portfolio -o json
# {"portfolio":{"totalUsdValue":"10250.00","chains":[{"chain":"ethereum","balance":{"native":"1.5","symbol":"ETH","usdValue":"3750.00"}},{"chain":"bitcoin","balance":{"native":"0.1","symbol":"BTC","usdValue":"6500.00"}}]},"currency":"USD"}

# Send transaction
vultisig send ethereum 0x... 0.1 -y --password "pass" -o json
# {"txHash":"0x...","chain":"ethereum","explorerUrl":"https://etherscan.io/tx/0x..."}

# Vault info
vultisig info -o json
# {"vault":{"id":"...","name":"...","type":"fast","chains":[...]}}

# Create vault (two-step)
vultisig create fast --name "w" --email "[email protected]" --password "p" --two-step -o json
# {"vaultId":"...","status":"pending_verification","verifyCommand":"vultisig verify ... --code <OTP>"}

# Verify vault
vultisig verify <id> --code 123456 -o json
# {"verified":true,"vault":{"id":"...","name":"...","type":"fast"}}

Common Workflows

Workflow: First-Time Setup (Non-Interactive)

# 1. Create vault (non-interactive, returns vault ID)
RESULT=$(vultisig create fast --name "agent-wallet" --email "[email protected]" --password "SecurePass123!" --two-step -o json)
VAULT_ID=$(echo "$RESULT" | jq -r '.vaultId')

# 2. User retrieves OTP from email, then verify
vultisig verify "$VAULT_ID" --code 123456 -o json

# 3. Enable desired chains
vultisig chains --add-all

# 4. Get addresses
vultisig addresses -o json

# 5. Check balances
vultisig balance -o json

Workflow: Send Crypto

# 1. Check balance
BALANCE=$(vultisig balance ethereum -o json | jq -r '.balance.native')

# 2. Verify sufficient funds
if (( $(echo "$BALANCE > 0.1" | bc -l) )); then
  # 3. Send
  vultisig send ethereum 0xRecipient... 0.1 --password "$VAULT_PASSWORD" -y -o json
fi

Workflow: Cross-Chain Swap

# 1. Get quote
QUOTE=$(vultisig swap-quote ethereum bitcoin 0.1 -o json)
echo "Expected output: $(echo $QUOTE | jq -r '.expectedOutput') BTC"

# 2. Execute swap
vultisig swap ethereum bitcoin 0.1 --password "$VAULT_PASSWORD" -y -o json

Workflow: Backup Vault

# Export encrypted backup
vultisig export /backups/ --password "$VAULT_PASSWORD"

Environment Variables

VULTISIG_VAULT="my-wallet"       # Pre-select vault by name/ID
VAULT_PASSWORD="password"         # Vault password (use with caution)
VULTISIG_SILENT=1                # Suppress spinners/info messages
VULTISIG_NO_COLOR=1              # Disable colored output

Error Handling

Exit Code	Meaning
0	Success
1	General error
2	Invalid usage
4	Authentication error
5	Network error
6	Vault error
7	Transaction error

See references/errors.md for common errors and solutions.

Supported Chains

36+ blockchains including:

• EVM: Ethereum, Polygon, Arbitrum, Optimism, BSC, Base, Avalanche, Blast, Cronos, ZkSync, Hyperliquid, Mantle, Sei
• UTXO: Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Dash, Zcash
• Cosmos: Cosmos, THORChain, MayaChain, Osmosis, Dydx, Kujira, Terra, Noble, Akash
• Other: Solana, Sui, Polkadot, TON, Ripple, Tron, Cardano

See references/chains.md for full list with details.

Resources

• GitHub Repository
• Full CLI Documentation
• SDK Documentation