wallet-cli

USB-based CLI for Ledger wallet flows. Networks: bitcoin, ethereum, solana (mainnet + testnets).

Install globally with a user-preferred package manager — npm i -g @ledgerhq/wallet-cli, pnpm add -g @ledgerhq/wallet-cli, yarn global add @ledgerhq/wallet-cli, or bun add -g @ledgerhq/wallet-cli. Run: wallet-cli [flags].

Concepts & rationale: for why a command behaves the way it does, or to surface a safety rule that this skill states tersely (genuine check, receive-address verification, sessions, sandbox, device contention), read references/business-logic.md.

Session first: When invoked without a specific task, immediately run session view — do not ask the user what to do first. Show the result, then ask what to do next. If labels exist, skip account discover.

Sandbox: account discover, receive (without --no-verify), send (without --dry-run), genuine-check, swap execute, earn deposit (without --dry-run), earn withdraw (without --dry-run), ring init must use dangerouslyDisableSandbox: true — these open the device over USB (via the node-webusb DMK transport) and are blocked by USB restrictions. ring encrypt, ring decrypt, ring destroy, agent-intent enroll, agent-intent recover, agent-intent sync, agent-intent send and agent-intent swap (without --dry-run), agent-intent intents, agent-intent status, agent-intent cancel never open the device but also need the bypass — they're blocked by OS keychain access restrictions instead (agent-intent enroll/recover also hold a WebSocket to the Trustchain relay). ring keys needs neither, and neither does agent-intent list/show: they only read the local session file, so they run without the bypass.

Device contention: Never run two device commands in parallel — they fail with [object Object] or garbled APDU. Run sequentially.

Device readiness: Before running a device command, briefly describe what you're about to do. The CLI prompts for device interaction itself — don't time out or kill the command. Exception: genuine-check exits immediately ([✖] Wrong app. Open Ledger dashboard., exit code 4) if any currency app is open — unlike the other device commands, it targets the dashboard and has no auto-launch path. Ensure the device is on the dashboard before running; if it exits, ask the user to back out to the dashboard and re-run.

Ambiguous requests — ask, don't guess. If a required parameter is missing or unclear (no recipient for send, no network for account discover, an amount with no ticker), stop and ask. A wrong guess on a hardware wallet flow can mean irreversible fund loss.