Vultisig CLI

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

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 "agent@example.com" \
  --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 agent@example.com --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 "agent@example.com" --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

Wallet Operations

Swap Operations

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.

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

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

Chain & Token Management

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.

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

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 "e@e.com" --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 "agent@example.com" --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

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