@vultisig/cli 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @vultisig/cli
 
+## 2.12.0
+
+### Patch Changes
+
+- Updated dependencies [[`403d5d5`](https://github.com/vultisig/vultisig-sdk/commit/403d5d5f7c7dba3e45cb818899db00f765541ecf)]:
+  - @vultisig/core-chain@2.21.0
+  - @vultisig/sdk@2.12.0
+  - @vultisig/rujira@45.0.0
+
+## 2.11.0
+
+### Patch Changes
+
+- [#899](https://github.com/vultisig/vultisig-sdk/pull/899) [`00ede74`](https://github.com/vultisig/vultisig-sdk/commit/00ede74e6db1bd08ded0b25cc32c1f477e6b0d22) Thanks [@neavra](https://github.com/neavra)! - agent: resolve the vault password from the keyring/env chain before prompting
+
+  `vultisig agent` (including `agent ask` and `--via-agent`) now resolves the vault
+  password from the in-memory cache → OS keyring (`vsig auth setup`) →
+  `VAULT_PASSWORDS`/`VAULT_PASSWORD` env chain before falling back to an
+  interactive prompt. Headless operators who configured the keyring or env no
+  longer have to pass `--password` on argv (which exposed the secret to `ps` and
+  shell history). `--password` still works but is de-emphasized and now emits a
+  stderr warning pointing at the keyring/env path.
+
+- Updated dependencies [[`9e72781`](https://github.com/vultisig/vultisig-sdk/commit/9e7278125bd8bc722a26ab3a1f91ba1be03054d1)]:
+  - @vultisig/core-chain@2.20.0
+  - @vultisig/sdk@2.11.0
+  - @vultisig/rujira@44.0.0
+
 ## 2.10.0
 
 ### Patch Changes

package/README.md

@@ -60,6 +60,7 @@ vultisig create fast --name "My Wallet" --password "mypassword" --email user@exa
 ```
 
 You'll be prompted to:
+
 1. Enter the verification code sent to your email
 
 ### Create a Secure Vault (Multi-Device)
@@ -69,16 +70,19 @@ vultisig create secure --name "Team Wallet" --shares 3
 ```
 
 This creates a secure vault with configurable N-of-M threshold:
+
 1. A QR code displays in your terminal
 2. Other participants scan with Vultisig mobile app (iOS/Android)
 3. Once all devices join, keygen runs automatically
 4. Vault is created and ready to use
 
 **Secure vault options:**
+
 - `--shares <n>` - Number of participating devices (default: 3)
 - `--threshold <n>` - Signing threshold (default: 2)
 
 **Example session:**
+
 ```bash
 $ vultisig create secure --name "Team Wallet" --shares 3
 
@@ -115,6 +119,7 @@ vultisig create-from-seedphrase secure --name "Team Wallet" --shares 3
 ```
 
 **Import options:**
+
 - `--mnemonic <words>` - Recovery phrase (space-separated words)
 - `--discover-chains` - Scan chains for existing balances before import
 - `--chains <chains>` - Specific chains to enable (comma-separated)
@@ -125,6 +130,7 @@ When `--mnemonic` is not provided, you'll be prompted to enter it securely (mask
 > **Note:** Phantom wallet uses a non-standard derivation path for Solana. If your seedphrase was originally created in Phantom and you're importing Solana funds, use `--use-phantom-solana-path`. When using `--discover-chains`, this is auto-detected.
 
 **Example session:**
+
 ```bash
 $ vultisig create-from-seedphrase fast --name "My Wallet" --email user@example.com --password "mypassword" --discover-chains
 
@@ -213,34 +219,37 @@ vultisig -i
 
 ### Vault Management
 
-| Command | Description |
-|---------|-------------|
-| `create fast` | Create a new fast vault (server-assisted 2-of-2) |
-| `create secure` | Create a secure vault (multi-device MPC) |
-| `import <file>` | Import vault from .vult file |
-| `delete [vault]` | Delete a vault from local storage |
-| `create-from-seedphrase fast` | Import seedphrase as FastVault (2-of-2) |
-| `create-from-seedphrase secure` | Import seedphrase as SecureVault (N-of-M) |
-| `join secure` | Join an existing SecureVault creation session |
-| `export [path]` | Export vault to file |
-| `verify <vaultId>` | Verify vault with email code |
-| `vaults` | List all stored vaults |
-| `switch <vaultId>` | Switch to a different vault |
-| `rename <newName>` | Rename the active vault |
-| `info` | Show detailed vault information |
+| Command                         | Description                                      |
+| ------------------------------- | ------------------------------------------------ |
+| `create fast`                   | Create a new fast vault (server-assisted 2-of-2) |
+| `create secure`                 | Create a secure vault (multi-device MPC)         |
+| `import <file>`                 | Import vault from .vult file                     |
+| `delete [vault]`                | Delete a vault from local storage                |
+| `create-from-seedphrase fast`   | Import seedphrase as FastVault (2-of-2)          |
+| `create-from-seedphrase secure` | Import seedphrase as SecureVault (N-of-M)        |
+| `join secure`                   | Join an existing SecureVault creation session    |
+| `export [path]`                 | Export vault to file                             |
+| `verify <vaultId>`              | Verify vault with email code                     |
+| `vaults`                        | List all stored vaults                           |
+| `switch <vaultId>`              | Switch to a different vault                      |
+| `rename <newName>`              | Rename the active vault                          |
+| `info`                          | Show detailed vault information                  |
 
 **Create fast options:**
+
 - `--name <name>` - Vault name (required)
 - `--password <password>` - Vault password (required)
 - `--email <email>` - Email for verification (required)
 
 **Create secure options:**
+
 - `--name <name>` - Vault name (required)
 - `--password <password>` - Vault password (optional)
 - `--shares <n>` - Number of devices (default: 3)
 - `--threshold <n>` - Signing threshold (default: 2)
 
 **Delete options:**
+
 - `[vault]` - Vault name or ID to delete (defaults to active vault)
 - `-y, --yes` - Skip confirmation prompt
 
@@ -259,6 +268,7 @@ vultisig delete "Test Vault" --yes
 ```
 
 **Join secure options:**
+
 - `--qr <payload>` - QR code payload from initiator (vultisig://...)
 - `--qr-file <path>` - Read QR payload from file
 - `--mnemonic <words>` - Seedphrase (required for seedphrase-based sessions)
@@ -266,6 +276,7 @@ vultisig delete "Test Vault" --yes
 - `--devices <n>` - Total devices in session (default: 2)
 
 **Create-from-seedphrase fast options:**
+
 - `--name <name>` - Vault name (required)
 - `--email <email>` - Email for verification (required)
 - `--password <password>` - Vault password (required)
@@ -275,6 +286,7 @@ vultisig delete "Test Vault" --yes
 - `--use-phantom-solana-path` - Use Phantom wallet derivation path for Solana
 
 **Create-from-seedphrase secure options:**
+
 - `--name <name>` - Vault name (required)
 - `--shares <n>` - Number of devices (default: 3)
 - `--threshold <n>` - Signing threshold (default: ceil((shares+1)/2))
@@ -285,6 +297,7 @@ vultisig delete "Test Vault" --yes
 - `--use-phantom-solana-path` - Use Phantom wallet derivation path for Solana
 
 **Export options:**
+
 - `[path]` - Output file or directory (defaults to SDK-generated filename in current directory)
 - `--password <password>` - Password to unlock encrypted vaults
 - `--exportPassword <password>` - Password to encrypt the export file (defaults to `--password` if provided)
@@ -309,27 +322,27 @@ vultisig export
 
 ### Wallet Operations
 
-| Command | Description |
-|---------|-------------|
-| `balance [chain]` | Show balance for a chain or all chains |
-| `send <chain> <to> <amount>` | Send tokens to an address |
-| `addresses` | Show all vault addresses |
-| `portfolio` | Show total portfolio value |
+| Command                      | Description                            |
+| ---------------------------- | -------------------------------------- |
+| `balance [chain]`            | Show balance for a chain or all chains |
+| `send <chain> <to> <amount>` | Send tokens to an address              |
+| `addresses`                  | Show all vault addresses               |
+| `portfolio`                  | Show total portfolio value             |
 
 ### Chain & Token Management
 
-| Command | Description |
-|---------|-------------|
-| `chains` | List and manage chains (--add, --remove) |
-| `tokens <chain>` | List and manage tokens for a chain |
+| Command          | Description                              |
+| ---------------- | ---------------------------------------- |
+| `chains`         | List and manage chains (--add, --remove) |
+| `tokens <chain>` | List and manage tokens for a chain       |
 
 ### Swap Operations
 
-| Command | Description |
-|---------|-------------|
-| `swap-chains` | List chains that support swaps |
-| `swap-quote <from> <to> <amount>` | Get a swap quote |
-| `swap <from> <to> <amount>` | Execute a swap |
+| Command                           | Description                    |
+| --------------------------------- | ------------------------------ |
+| `swap-chains`                     | List chains that support swaps |
+| `swap-quote <from> <to> <amount>` | Get a swap quote               |
+| `swap <from> <to> <amount>`       | Execute a swap                 |
 
 ```bash
 # Get a swap quote
@@ -349,11 +362,11 @@ Swap quotes and previews show your VULT discount tier when affiliate fees are ap
 
 ### Advanced Operations
 
-| Command | Description |
-|---------|-------------|
-| `sign` | Sign pre-hashed bytes for custom transactions |
-| `broadcast` | Broadcast a pre-signed raw transaction |
-| `tx-status <chain> <txHash>` | Check transaction confirmation status |
+| Command                      | Description                                   |
+| ---------------------------- | --------------------------------------------- |
+| `sign`                       | Sign pre-hashed bytes for custom transactions |
+| `broadcast`                  | Broadcast a pre-signed raw transaction        |
+| `tx-status <chain> <txHash>` | Check transaction confirmation status         |
 
 #### Transaction Status
 
@@ -371,6 +384,7 @@ vultisig tx-status ethereum 0x9f8e7d6c... -o json
 ```
 
 **Output:**
+
 ```
 ✓ Transaction status: success
 Status: success
@@ -379,6 +393,7 @@ Explorer: https://etherscan.io/tx/0x9f8e7d6c...
 ```
 
 **JSON output:**
+
 ```json
 {
   "chain": "ethereum",
@@ -409,6 +424,7 @@ vultisig sign --chain ethereum --bytes "..." -o json
 ```
 
 **Output:**
+
 ```
 Signature: <base64-encoded signature>
 Recovery: 0
@@ -416,6 +432,7 @@ Format: ecdsa
 ```
 
 **JSON output:**
+
 ```json
 {
   "signature": "<base64>",
@@ -443,6 +460,7 @@ vultisig broadcast --chain sui --raw-tx '{"unsignedTx":"...","signature":"..."}'
 ```
 
 **Output:**
+
 ```
 TX Hash: 0x9f8e7d6c...
 Explorer: https://etherscan.io/tx/0x9f8e7d6c...
@@ -450,17 +468,17 @@ Explorer: https://etherscan.io/tx/0x9f8e7d6c...
 
 **Supported broadcast formats by chain:**
 
-| Chain | `--raw-tx` Format |
-|-------|-------------------|
-| EVM (Ethereum, Polygon, etc.) | Hex-encoded signed tx |
-| UTXO (Bitcoin, Litecoin, etc.) | Hex-encoded raw tx |
-| Solana | Base64-encoded tx bytes |
-| Sui | JSON: `{"unsignedTx":"...","signature":"..."}` |
-| Cosmos | JSON: `{"tx_bytes":"..."}` or base64 |
-| TON | Base64 BOC |
-| Polkadot | Hex-encoded extrinsic |
-| Ripple | Hex-encoded tx blob |
-| Tron | JSON tx object |
+| Chain                          | `--raw-tx` Format                              |
+| ------------------------------ | ---------------------------------------------- |
+| EVM (Ethereum, Polygon, etc.)  | Hex-encoded signed tx                          |
+| UTXO (Bitcoin, Litecoin, etc.) | Hex-encoded raw tx                             |
+| Solana                         | Base64-encoded tx bytes                        |
+| Sui                            | JSON: `{"unsignedTx":"...","signature":"..."}` |
+| Cosmos                         | JSON: `{"tx_bytes":"..."}` or base64           |
+| TON                            | Base64 BOC                                     |
+| Polkadot                       | Hex-encoded extrinsic                          |
+| Ripple                         | Hex-encoded tx blob                            |
+| Tron                           | JSON tx object                                 |
 
 #### Example: Custom EVM Transaction
 
@@ -614,6 +632,7 @@ vultisig create fast --name "Agent Wallet" --password "$VAULT_PASSWORD" --email
 ```
 
 JSON output for two-step create:
+
 ```json
 {
   "vaultId": "023118...",
@@ -626,23 +645,33 @@ JSON output for two-step create:
 
 #### Agent Ask (One-Shot Mode)
 
-Send a single natural-language message and get a structured response. Designed for AI-to-AI communication:
+Send a single natural-language message and get a structured response. Designed for AI-to-AI communication.
+
+**Password resolution:** `agent ask` unlocks the vault from the keyring/env chain before prompting, so a headless operator never has to put the password on argv. Set it up **once** — store it in the OS keyring with `vsig auth setup` (recommended), or export `VAULT_PASSWORD` (or `VAULT_PASSWORDS="VaultName:pw ..."` for multiple vaults) — then run `agent ask` with **no** `--password`. The `--password` flag still works as a fallback but is discouraged: it exposes the secret to `ps` and shell history, and triggers a stderr warning.
 
 ```bash
-# Simple query
-vultisig agent ask "What is my ETH balance?" --password "$VAULT_PASSWORD"
+# Recommended: store the password once, then no --password on each call
+vsig auth setup                 # stores in the OS keyring
+# or: export VAULT_PASSWORD="..."
+
+# Simple query (password resolved from keyring/env)
+vultisig agent ask "What is my ETH balance?"
 
 # Execute a transaction
-vultisig agent ask "Send 0.01 ETH to 0x742d..." --password "$VAULT_PASSWORD"
+vultisig agent ask "Send 0.01 ETH to 0x742d..."
 
 # Continue a conversation (multi-turn)
-vultisig agent ask "Now swap it to USDC" --session abc123 --password "$VAULT_PASSWORD"
+vultisig agent ask "Now swap it to USDC" --session abc123
 
 # JSON output (for parsing)
-vultisig agent ask "Check my portfolio" --password "$VAULT_PASSWORD" --json
+vultisig agent ask "Check my portfolio" --json
+
+# Fallback only — exposes the secret to `ps`/shell history (emits a warning)
+vultisig agent ask "What is my ETH balance?" --password "$VAULT_PASSWORD"
 ```
 
 **Text output (default):**
+
 ```
 session:abc123-def456
 
@@ -653,12 +682,21 @@ explorer:https://etherscan.io/tx/0x9f8e7d6c...
 ```
 
 **JSON output (`--json`):**
+
 ```json
 {
   "session_id": "abc123-def456",
   "response": "Your ETH balance is 1.5 ETH ($3,750.00 USD).",
   "tool_calls": [
-    { "action": "get_balances", "success": true, "data": { "balances": [{ "chain": "Ethereum", "symbol": "ETH", "amount": "1.5", "decimals": 18, "raw_amount": "1500000000000000000" }] } }
+    {
+      "action": "get_balances",
+      "success": true,
+      "data": {
+        "balances": [
+          { "chain": "Ethereum", "symbol": "ETH", "amount": "1.5", "decimals": 18, "raw_amount": "1500000000000000000" }
+        ]
+      }
+    }
   ],
   "transactions": [
     { "hash": "0x9f8e7d6c...", "chain": "ethereum", "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..." }
@@ -678,28 +716,29 @@ Each entry in `tool_calls` may include `code` when `success` is false (same valu
 
 Orchestrators should branch on `code`. The message in `error` / `message` stays human-readable and may change between releases.
 
-| Code | Typical meaning |
-|------|-----------------|
-| `BACKEND_UNREACHABLE` | Agent health check failed or backend not responding |
-| `AUTH_FAILED` | Auth/token failure, HTTP 401/403, or wrong vault password |
-| `VAULT_LOCKED` | Encrypted vault needs unlock (password) |
-| `PASSWORD_REQUIRED` | Password was not supplied when required (e.g. pipe mode or signing) |
-| `CONFIRMATION_REQUIRED` | User confirmation needed (pipe mode; message prefix `CONFIRMATION_REQUIRED:`) |
-| `ACTION_NOT_IMPLEMENTED` | Local executor does not implement this action type |
-| `INVALID_INPUT` | Bad parameters, unknown chain, malformed NDJSON input, etc. |
-| `NETWORK_ERROR` | RPC/fetch connectivity (includes many SDK `VaultError` network cases) |
-| `TIMEOUT` | Deadline exceeded, or abort where the message indicates a timeout |
-| `TRANSACTION_FAILED` | Build/broadcast/gas errors mapped from the SDK |
-| `SIGNING_FAILED` | MPC/signing failed |
-| `SESSION_NOT_INITIALIZED` | Internal session state error |
-| `UNKNOWN_ERROR` | Unclassified failure (default for opaque SSE `error` events). Plain `AbortError` without “timeout” in the message maps here. |
+| Code                      | Typical meaning                                                                                                              |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `BACKEND_UNREACHABLE`     | Agent health check failed or backend not responding                                                                          |
+| `AUTH_FAILED`             | Auth/token failure, HTTP 401/403, or wrong vault password                                                                    |
+| `VAULT_LOCKED`            | Encrypted vault needs unlock (password)                                                                                      |
+| `PASSWORD_REQUIRED`       | Password was not supplied when required (e.g. pipe mode or signing)                                                          |
+| `CONFIRMATION_REQUIRED`   | User confirmation needed (pipe mode; message prefix `CONFIRMATION_REQUIRED:`)                                                |
+| `ACTION_NOT_IMPLEMENTED`  | Local executor does not implement this action type                                                                           |
+| `INVALID_INPUT`           | Bad parameters, unknown chain, malformed NDJSON input, etc.                                                                  |
+| `NETWORK_ERROR`           | RPC/fetch connectivity (includes many SDK `VaultError` network cases)                                                        |
+| `TIMEOUT`                 | Deadline exceeded, or abort where the message indicates a timeout                                                            |
+| `TRANSACTION_FAILED`      | Build/broadcast/gas errors mapped from the SDK                                                                               |
+| `SIGNING_FAILED`          | MPC/signing failed                                                                                                           |
+| `SESSION_NOT_INITIALIZED` | Internal session state error                                                                                                 |
+| `UNKNOWN_ERROR`           | Unclassified failure (default for opaque SSE `error` events). Plain `AbortError` without “timeout” in the message maps here. |
 
 SSE `error` events may optionally include a `code` field from the backend; if it matches one of the values above, it is passed through unchanged. Otherwise the CLI infers a code from the message.
 
 **Agent ask options:**
+
 - `--session <id>` - Continue an existing conversation
 - `--backend-url <url>` - Agent backend URL (default: https://abe.vultisig.com)
-- `--password <password>` - Vault password for signing
+- `--password <password>` - Vault password (fallback only; prefer the keyring/`VAULT_PASSWORD` env — see **Password resolution** above)
 - `--verbose` - Show tool calls and debug info on stderr
 - `--json` - Output structured JSON
 
@@ -711,15 +750,18 @@ For interactive TUI or piped agent-to-agent communication:
 # Interactive TUI with chat interface
 vultisig agent
 
-# Pipe mode for agent-to-agent (NDJSON)
-vultisig agent --via-agent --password "$VAULT_PASSWORD"
+# Pipe mode for agent-to-agent (NDJSON) — password resolved from keyring/env
+vultisig agent --via-agent
 ```
 
+The vault password is resolved from the keyring/env chain (`vsig auth setup` or `VAULT_PASSWORD`) the same way as `agent ask`; in `--via-agent` mode it can also be supplied over the pipe protocol (see below). `--password` remains a discouraged fallback.
+
 **Agent chat options:**
+
 - `--via-agent` - NDJSON pipe mode for agent-to-agent communication (24h password cache)
 - `--verbose` - Show detailed tool call parameters
 - `--backend-url <url>` - Agent backend URL
-- `--password <password>` - Vault password
+- `--password <password>` - Vault password (fallback only; prefer the keyring/`VAULT_PASSWORD` env)
 - `--password-ttl <ms>` - Password cache TTL (default: 5min, 24h for `--via-agent`)
 - `--session-id <id>` - Resume an existing session
 
@@ -729,27 +771,27 @@ The pipe interface uses NDJSON (one JSON object per line) on stdin/stdout. Desig
 
 **Input commands** (send on stdin):
 
-| Type | Fields | Purpose |
-|------|--------|---------|
-| `message` | `content: string` | Send a natural-language message |
-| `confirm` | `confirmed: boolean` | Respond to a confirmation request |
-| `password` | `password: string` | Provide vault password when requested |
+| Type       | Fields               | Purpose                               |
+| ---------- | -------------------- | ------------------------------------- |
+| `message`  | `content: string`    | Send a natural-language message       |
+| `confirm`  | `confirmed: boolean` | Respond to a confirmation request     |
+| `password` | `password: string`   | Provide vault password when requested |
 
 **Output events** (emitted on stdout):
 
-| Type | Fields | When |
-|------|--------|------|
-| `ready` | `vault, addresses` | Session initialized, addresses for all chains |
-| `session` | `id` | Conversation ID for resuming later |
-| `history` | `messages[]` | Previous messages when resuming a session |
-| `text_delta` | `delta` | Streaming text chunk from the agent |
-| `tool_call` | `id, action, params?, status` | Action started (`running`) |
-| `tool_result` | `id, action, success, data?, error?, code?` | Action completed (`code` when `success` is false) |
-| `tx_status` | `tx_hash, chain, status, explorer_url?` | Transaction broadcast/confirmed/failed |
-| `assistant` | `content` | Full assistant response |
-| `suggestions` | `suggestions[]` | Suggested follow-up actions |
-| `error` | `message, code` | Error or control signal (`PASSWORD_REQUIRED`, `CONFIRMATION_REQUIRED: …`; always includes stable `code`) |
-| `done` | `{}` | Response cycle complete |
+| Type          | Fields                                      | When                                                                                                     |
+| ------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `ready`       | `vault, addresses`                          | Session initialized, addresses for all chains                                                            |
+| `session`     | `id`                                        | Conversation ID for resuming later                                                                       |
+| `history`     | `messages[]`                                | Previous messages when resuming a session                                                                |
+| `text_delta`  | `delta`                                     | Streaming text chunk from the agent                                                                      |
+| `tool_call`   | `id, action, params?, status`               | Action started (`running`)                                                                               |
+| `tool_result` | `id, action, success, data?, error?, code?` | Action completed (`code` when `success` is false)                                                        |
+| `tx_status`   | `tx_hash, chain, status, explorer_url?`     | Transaction broadcast/confirmed/failed                                                                   |
+| `assistant`   | `content`                                   | Full assistant response                                                                                  |
+| `suggestions` | `suggestions[]`                             | Suggested follow-up actions                                                                              |
+| `error`       | `message, code`                             | Error or control signal (`PASSWORD_REQUIRED`, `CONFIRMATION_REQUIRED: …`; always includes stable `code`) |
+| `done`        | `{}`                                        | Response cycle complete                                                                                  |
 
 **Example session:**
 
@@ -782,13 +824,13 @@ vultisig agent sessions delete abc123
 
 #### Agent Command Summary
 
-| Command | Description |
-|---------|-------------|
-| `agent ask <message>` | One-shot: send message, get response, exit |
-| `agent` | Interactive TUI chat interface |
-| `agent --via-agent` | NDJSON pipe mode for agent-to-agent |
-| `agent sessions list` | List chat sessions |
-| `agent sessions delete <id>` | Delete a session |
+| Command                      | Description                                |
+| ---------------------------- | ------------------------------------------ |
+| `agent ask <message>`        | One-shot: send message, get response, exit |
+| `agent`                      | Interactive TUI chat interface             |
+| `agent --via-agent`          | NDJSON pipe mode for agent-to-agent        |
+| `agent sessions list`        | List chat sessions                         |
+| `agent sessions delete <id>` | Delete a session                           |
 
 #### Environment Variables for Automation
 
@@ -808,12 +850,12 @@ VULTISIG_SILENT=1
 
 ### Settings
 
-| Command | Description |
-|---------|-------------|
-| `currency [code]` | View or set currency preference |
-| `server` | Check server connectivity |
-| `discount` | Show your VULT discount tier for swap fees |
-| `address-book` | Manage saved addresses |
+| Command           | Description                                |
+| ----------------- | ------------------------------------------ |
+| `currency [code]` | View or set currency preference            |
+| `server`          | Check server connectivity                  |
+| `discount`        | Show your VULT discount tier for swap fees |
+| `address-book`    | Manage saved addresses                     |
 
 #### Discount Tiers
 
@@ -828,6 +870,7 @@ vultisig discount --refresh
 ```
 
 **Output:**
+
 ```text
 +----------------------------------------+
 |          VULT Discount Tier            |
@@ -845,41 +888,41 @@ vultisig discount --refresh
 
 **Tier levels:**
 
-| Tier | VULT Required | Swap Fee | Discount |
-|------|---------------|----------|----------|
-| None | 0 | 50 bps | - |
-| Bronze | 1,500 | 45 bps | 5 bps |
-| Silver | 3,000 | 40 bps | 10 bps |
-| Gold | 7,500 | 30 bps | 20 bps |
-| Platinum | 15,000 | 25 bps | 25 bps |
-| Diamond | 100,000 | 15 bps | 35 bps |
-| Ultimate | 1,000,000 | 0 bps | 50 bps |
+| Tier     | VULT Required | Swap Fee | Discount |
+| -------- | ------------- | -------- | -------- |
+| None     | 0             | 50 bps   | -        |
+| Bronze   | 1,500         | 45 bps   | 5 bps    |
+| Silver   | 3,000         | 40 bps   | 10 bps   |
+| Gold     | 7,500         | 30 bps   | 20 bps   |
+| Platinum | 15,000        | 25 bps   | 25 bps   |
+| Diamond  | 100,000       | 15 bps   | 35 bps   |
+| Ultimate | 1,000,000     | 0 bps    | 50 bps   |
 
 Thorguard NFT holders receive a free tier upgrade (up to gold tier).
 
 ### CLI Management
 
-| Command | Description |
-|---------|-------------|
-| `version` | Show detailed version info |
-| `update` | Check for updates |
-| `completion` | Generate shell completion |
+| Command      | Description                |
+| ------------ | -------------------------- |
+| `version`    | Show detailed version info |
+| `update`     | Check for updates          |
+| `completion` | Generate shell completion  |
 
 ### Interactive Shell Commands
 
-| Command | Description |
-|---------|-------------|
-| `vault <name>` | Switch to a different vault |
-| `vaults` | List all vaults |
-| `create` | Create a new vault |
-| `import <file>` | Import vault from file |
-| `delete [name]` | Delete a vault |
-| `lock` | Lock vault (clear cached password) |
-| `unlock` | Unlock vault (cache password) |
-| `status` | Show vault status |
-| `help` | Show available commands |
-| `.clear` | Clear the screen |
-| `.exit` | Exit the shell |
+| Command         | Description                        |
+| --------------- | ---------------------------------- |
+| `vault <name>`  | Switch to a different vault        |
+| `vaults`        | List all vaults                    |
+| `create`        | Create a new vault                 |
+| `import <file>` | Import vault from file             |
+| `delete [name]` | Delete a vault                     |
+| `lock`          | Lock vault (clear cached password) |
+| `unlock`        | Unlock vault (cache password)      |
+| `status`        | Show vault status                  |
+| `help`          | Show available commands            |
+| `.clear`        | Clear the screen                   |
+| `.exit`         | Exit the shell                     |
 
 ## Global Options
 
@@ -920,6 +963,7 @@ Use `-o json` or `--output json` to get structured JSON output. JSON mode automa
 # Get balance as JSON
 vultisig balance ethereum -o json
 ```
+
 ```json
 {
   "chain": "ethereum",
@@ -935,6 +979,7 @@ vultisig balance ethereum -o json
 # Get all balances as JSON
 vultisig balance -o json
 ```
+
 ```json
 {
   "balances": [
@@ -948,6 +993,7 @@ vultisig balance -o json
 # Get portfolio as JSON
 vultisig portfolio -o json
 ```
+
 ```json
 {
   "portfolio": {
@@ -962,11 +1008,10 @@ vultisig portfolio -o json
 # List vaults as JSON
 vultisig vaults -o json
 ```
+
 ```json
 {
-  "vaults": [
-    { "id": "abc123", "name": "Main Wallet", "isActive": true }
-  ],
+  "vaults": [{ "id": "abc123", "name": "Main Wallet", "isActive": true }],
   "activeVaultId": "abc123"
 }
 ```
@@ -975,6 +1020,7 @@ vultisig vaults -o json
 # Get swap quote as JSON
 vultisig swap-quote ethereum thorchain 0.1 -o json
 ```
+
 ```json
 {
   "quote": {
@@ -988,6 +1034,7 @@ vultisig swap-quote ethereum thorchain 0.1 -o json
 ```
 
 JSON output is ideal for:
+
 - Scripting and automation
 - Parsing output programmatically
 - Integration with other tools (e.g., `jq`):
@@ -1056,6 +1103,7 @@ Configuration is stored in `~/.vultisig/`:
 ## Supported Chains
 
 40+ blockchains including:
+
 - **EVM**: Ethereum, Polygon, Arbitrum, Optimism, BSC, Base, Avalanche
 - **UTXO**: Bitcoin, Litecoin, Dogecoin, Dash, Zcash
 - **Cosmos**: Cosmos Hub, THORChain, Maya, Dydx, Kujira
@@ -1063,22 +1111,23 @@ Configuration is stored in `~/.vultisig/`:
 
 ## Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Invalid usage |
-| 3 | Configuration error |
-| 4 | Authentication error |
-| 5 | Network error |
-| 6 | Vault error |
-| 7 | Transaction error |
+| Code | Meaning              |
+| ---- | -------------------- |
+| 0    | Success              |
+| 1    | General error        |
+| 2    | Invalid usage        |
+| 3    | Configuration error  |
+| 4    | Authentication error |
+| 5    | Network error        |
+| 6    | Vault error          |
+| 7    | Transaction error    |
 
 ## Troubleshooting
 
 ### "No active vault" error
 
 Create or import a vault first:
+
 ```bash
 vultisig create fast --name "My Wallet" --password "mypassword" --email user@example.com
 # or

package/dist/index.js

@@ -1140,7 +1140,7 @@ var init_size = __esm({
 var version;
 var init_version = __esm({
   "../../node_modules/viem/_esm/errors/version.js"() {
-    version = "2.52.2";
+    version = "2.53.1";
   }
 });
 
@@ -5188,6 +5188,13 @@ function getCachedPassword(vaultId, vaultName) {
   if (passwordCache.has(vaultId)) return passwordCache.get(vaultId);
   return null;
 }
+function clearCachedPassword(vaultIdOrName) {
+  if (vaultIdOrName) {
+    passwordCache.delete(vaultIdOrName);
+  } else {
+    passwordCache.clear();
+  }
+}
 function parseVaultPasswords() {
   const passwordMap = /* @__PURE__ */ new Map();
   const passwordsEnv = process.env.VAULT_PASSWORDS;
@@ -5232,7 +5239,7 @@ async function promptForPassword(vaultName, vaultId) {
   ]);
   return password;
 }
-async function getPassword(vaultId, vaultName) {
+async function resolvePasswordNonInteractive(vaultId, vaultName) {
   const cachedPassword = getCachedPassword(vaultId, vaultName);
   if (cachedPassword) {
     return cachedPassword;
@@ -5252,6 +5259,13 @@ async function getPassword(vaultId, vaultName) {
     if (vaultName) cachePassword(vaultName, envPassword);
     return envPassword;
   }
+  return null;
+}
+async function getPassword(vaultId, vaultName) {
+  const resolved = await resolvePasswordNonInteractive(vaultId, vaultName);
+  if (resolved) {
+    return resolved;
+  }
   if (isSilent() || isJsonOutput() || isNonInteractive()) {
     throw new Error(
       "Password required but not provided. Set VAULT_PASSWORD or VAULT_PASSWORDS environment variable, or use --password flag."
@@ -12163,6 +12177,66 @@ var AgentSession = class {
       this.executor.setPassword(config.password);
     }
   }
+  /**
+   * Unlock the vault before auth when it's encrypted. Resolve the password from
+   * the keyring/env chain (in-memory cache → OS keyring → VAULT_PASSWORDS/
+   * VAULT_PASSWORD env) BEFORE prompting, so a headless operator who set up the
+   * keyring or env never has to put a funds-controlling secret on argv. argv
+   * `--password` (config.password) still works but is de-emphasized: it lands
+   * the secret in `ps`/shell history, so its use warns. Only when the chain
+   * resolves nothing do we fall back to the mode's own interactive prompt (TUI
+   * readline / via-agent protocol; ask-mode throws). A stale stored password is
+   * cleared and re-prompted in interactive modes rather than stranding init.
+   */
+  async unlockEncryptedVault(ui) {
+    if (!this.vault.isEncrypted) {
+      return;
+    }
+    let password;
+    let fromStoredChain = false;
+    if (this.config.password) {
+      process.stderr.write(
+        "Warning: passing the vault password via --password exposes it to `ps` and shell history. Prefer the OS keyring (`vsig auth setup`) or the VAULT_PASSWORD env var.\n"
+      );
+      password = this.config.password;
+    } else {
+      const resolved = await resolvePasswordNonInteractive(this.vault.id, this.vault.name);
+      if (resolved !== null) {
+        password = resolved;
+        fromStoredChain = true;
+      } else {
+        password = await ui.requestPassword();
+      }
+    }
+    try {
+      await this.vault.unlock?.(password);
+    } catch (unlockErr) {
+      if (!fromStoredChain) throw unlockErr;
+      password = await this.recoverFromStaleStoredPassword(ui);
+    }
+    this.executor.setPassword(password);
+  }
+  /**
+   * The stored (keyring/env) password was rejected by unlock. Drop it so it
+   * isn't reused, then recover: ask mode has no interactive prompt (its
+   * requestPassword throws the misleading "use --password flag"), so surface the
+   * real cause; interactive modes (TUI / via-agent) re-prompt once and cache the
+   * winner. Returns the password that successfully unlocked the vault.
+   */
+  async recoverFromStaleStoredPassword(ui) {
+    clearCachedPassword(this.vault.id);
+    if (this.vault.name) clearCachedPassword(this.vault.name);
+    if (this.config.askMode) {
+      throw new Error(
+        `Stored vault password (keyring/env) was rejected for "${this.vault.name || this.vault.id}". Update it with \`vsig auth setup\` or the VAULT_PASSWORD env var, or pass --password.`
+      );
+    }
+    const password = await ui.requestPassword();
+    await this.vault.unlock?.(password);
+    cachePassword(this.vault.id, password);
+    if (this.vault.name) cachePassword(this.vault.name, password);
+    return password;
+  }
   /**
    * Initialize the session: health check, authenticate, create conversation.
    */
@@ -12172,11 +12246,7 @@ var AgentSession = class {
       throw new Error(`Agent backend unreachable at ${this.config.backendUrl}`);
     }
     try {
-      if (this.vault.isEncrypted) {
-        const password = this.config.password || await ui.requestPassword();
-        await this.vault.unlock?.(password);
-        this.executor.setPassword(password);
-      }
+      await this.unlockEncryptedVault(ui);
       const cached = loadCachedToken(this.publicKey);
       if (cached) {
         this.client.setAuthToken(cached);
@@ -13459,7 +13529,7 @@ var cachedVersion = null;
 function getVersion() {
   if (cachedVersion) return cachedVersion;
   if (true) {
-    cachedVersion = "2.10.0";
+    cachedVersion = "2.12.0";
     return cachedVersion;
   }
   try {
@@ -16152,7 +16222,10 @@ rujiraCmd.command("withdraw <asset> <amount> <l1Address>").description("Withdraw
     }
   )
 );
-var agentCmd = program.command("agent").description("AI-powered chat interface for wallet operations").option("--via-agent", "Use NDJSON pipe mode for agent-to-agent communication").option("--verbose", "Show detailed tool call parameters and debug output").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option("--password <password>", "Vault password for signing operations").option("--password-ttl <ms>", "Password cache TTL in milliseconds (default: 300000, 86400000/24h for --via-agent)").option("--session-id <id>", "Resume an existing session").option("--notification-url <url>", "Notification service URL for push notifications").option("--profile <api_id>", "Billing profile slug sent as X-Vultisig-Abe-Profile header").action(
+var agentCmd = program.command("agent").description("AI-powered chat interface for wallet operations").option("--via-agent", "Use NDJSON pipe mode for agent-to-agent communication").option("--verbose", "Show detailed tool call parameters and debug output").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option(
+  "--password <password>",
+  "Vault password (fallback; prefer the OS keyring via `vsig auth setup` or the VAULT_PASSWORD env var \u2014 --password is exposed to `ps`/shell history)"
+).option("--password-ttl <ms>", "Password cache TTL in milliseconds (default: 300000, 86400000/24h for --via-agent)").option("--session-id <id>", "Resume an existing session").option("--notification-url <url>", "Notification service URL for push notifications").option("--profile <api_id>", "Billing profile slug sent as X-Vultisig-Abe-Profile header").action(
   async (options) => {
     const MAX_TTL = 864e5;
     let passwordTTL;
@@ -16179,7 +16252,10 @@ var agentCmd = program.command("agent").description("AI-powered chat interface f
     });
   }
 );
-agentCmd.command("ask <message>").description("Send a single message and get the response (for AI agent integration)").option("--session <id>", "Continue an existing conversation").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option("--password <password>", "Vault password for signing operations").option("--verbose", "Show tool calls and debug info on stderr").option("--json", "Output structured JSON (deprecated: use --output json)").option("--profile <api_id>", "Billing profile slug sent as X-Vultisig-Abe-Profile header").option(
+agentCmd.command("ask <message>").description("Send a single message and get the response (for AI agent integration)").option("--session <id>", "Continue an existing conversation").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option(
+  "--password <password>",
+  "Vault password (fallback; prefer the OS keyring via `vsig auth setup` or the VAULT_PASSWORD env var \u2014 --password is exposed to `ps`/shell history)"
+).option("--verbose", "Show tool calls and debug info on stderr").option("--json", "Output structured JSON (deprecated: use --output json)").option("--profile <api_id>", "Billing profile slug sent as X-Vultisig-Abe-Profile header").option(
   "--yes",
   "Auto-approve signing/broadcast. Required for unattended signing; default is to NOT broadcast and report the proposed transaction instead."
 ).addHelpText(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vultisig/cli",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "The self-custody MPC wallet CLI for AI coding agents (Claude Code, Cursor, OpenCode). Natural-language agent mode, 36+ chains, DKLS23 threshold signatures. Seedless.",
   "type": "module",
   "bin": {
@@ -74,9 +74,9 @@
     "@napi-rs/keyring": "^1.3.0",
     "@noble/hashes": "^2.2.0",
     "@vultisig/client-shared": "^0.2.17",
-    "@vultisig/core-chain": "^2.19.0",
-    "@vultisig/rujira": "^43.0.0",
-    "@vultisig/sdk": "^2.10.0",
+    "@vultisig/core-chain": "^2.21.0",
+    "@vultisig/rujira": "^45.0.0",
+    "@vultisig/sdk": "^2.12.0",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
@@ -85,7 +85,7 @@
     "ora": "^9.4.0",
     "qrcode-terminal": "^0.12.0",
     "tabtab": "^3.0.2",
-    "viem": "^2.52.2",
+    "viem": "^2.53.1",
     "ws": "^8.21.0"
   },
   "devDependencies": {