Ledger Wallet CLI

wallet-cli

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

Run from repo root: pnpm --silent wallet-cli start <command> [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 (without --dry-run) 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.

Intent map

Map informal phrasings to commands. Account references use a session label (e.g. ethereum-1).

Out of scope — say no, don't improvise

If the user asks for any of the following, surface that wallet-cli does not support it yet rather than constructing a command:

• NFTs (mint, transfer, view).
• OpenPGP-compatible output or key-share / multi-recipient encryption (the ring commands encrypt with a per-user Ledger Key Ring, not a sharable key).
• send, receive, operations, or swap execute on testnets and layer 2s (e.g. Base).
• Custom chains not listed in the Networks line above.

Session & labels

account discover persists accounts. Each gets a label: <network>[-derivation][-env]-<n> (e.g. ethereum-1, bitcoin-native-1, ethereum-sepolia-1).

All --account flags accept a session label (e.g. ethereum-1). Run account discover first to populate the session.

Commands

*receive with --no-verify, send with --dry-run, and earn deposit/earn withdraw with --dry-run need no device and no sandbox bypass.

†TTY: whether the command requires an interactive terminal for user input.

‡ring init requires a password to protect the ring. WALLET_PASS must already be provided in the environment by the developer/user before the command runs — the agent never sets or injects it (see Non-TTY password injection).

‡‡ring destroy prompts for typed confirmation ("destroy"). Pipe it in non-interactive shells: echo "destroy" | wallet-cli ring destroy. If a password was set, WALLET_PASS must already be present in the environment (provided by the developer, not the agent).

session view / reset

pnpm --silent wallet-cli start session view
pnpm --silent wallet-cli start session reset

account discover

pnpm --silent wallet-cli start account discover ethereum
pnpm --silent wallet-cli start account discover bitcoin
pnpm --silent wallet-cli start account discover ethereum:sepolia

Networks: bitcoin (mainnet), ethereum, solana, ethereum:sepolia, bitcoin:testnet, solana:devnet.

receive

pnpm --silent wallet-cli start receive ethereum-1
pnpm --silent wallet-cli start receive ethereum-1 --no-verify  # skip device confirmation

If the on-screen address differs from the terminal address: do not share or use the address. Have the user disconnect the device and run genuine-check before retrying. See references/business-logic.md § Receive-address verification for context.

genuine-check

pnpm --silent wallet-cli start genuine-check
pnpm --silent wallet-cli start genuine-check --output json  # only if a downstream caller needs to parse the result

Preconditions: device unlocked and on the dashboard (exit any open app); host has internet access (the secure channel reaches Ledger's backend — offline runs fail).

balances

pnpm --silent wallet-cli start balances ethereum-1
pnpm --silent wallet-cli start balances ethereum-1 --output json

operations

pnpm --silent wallet-cli start operations ethereum-1
pnpm --silent wallet-cli start operations ethereum-1 --limit 20 --cursor <cursor>

Pagination: next cursor on stderr (human) or nextCursor in JSON.

send

pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '0.5 ETH'
pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '100 USDT'  # ERC-20
pnpm --silent wallet-cli start send bitcoin-native-1 --to bc1q... --amount '0.001 BTC' --fee-per-byte 15 --rbf
pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '0.5 ETH' --dry-run

Ticker is mandatory in --amount. No --token flag — ticker drives asset resolution.

Bitcoin flags: --fee-per-byte <sats>, --rbf

Solana flags: --mode send|stake.createAccount|stake.delegate|stake.undelegate|stake.withdraw, --validator <addr>, --stake-account <addr>, --memo <text>

EVM flags: --data <hex> — raw calldata for contract calls (0x-prefixed hex, even digit count). Use for contract interactions the CLI has no dedicated command for (e.g. WETH wrap/unwrap below). Omit for plain native/token transfers.

Contract calls with --data (wrap/unwrap example)

Canonical pattern: WETH wrap/unwrap. deposit() (wrap ETH → WETH, no args) is selector 0xd0e30db0, sent with --amount as the ETH value. withdraw(uint256) (unwrap WETH → ETH, one uint256 arg = amount in wei) is selector 0x2e1a7d4d followed by the amount left-padded to 32 bytes.

# wrap 0.5 ETH into WETH
pnpm --silent wallet-cli start send ethereum-1 --to <WETH_CONTRACT_ADDRESS> --amount '0.5 ETH' --data 0xd0e30db0

# unwrap 0.5 WETH back to ETH (0.5 ETH = 500000000000000000 wei = 6f05b59d3b20000 hex, padded to 32 bytes)
pnpm --silent wallet-cli start send ethereum-1 --to <WETH_CONTRACT_ADDRESS> --amount '0 ETH' --data 0x2e1a7d4d00000000000000000000000000000000000000000000000006f05b59d3b20000

Always run with --dry-run first to validate calldata before signing. The CLI cannot verify the semantic correctness of hand-supplied --data — the device screen is the last line of defense, so review the decoded call on-device before approving.

swap quote

Fetches quotes in parallel from the built-in provider list (no device required; addresses are resolved from session accounts).

Currencies: --from / -f and --to / -t are Ledger currency IDs — native assets (e.g. ethereum, bitcoin, solana) or token IDs when the token’s parent chain is a supported native swap currency (same IDs the CLI allows for swap). They are not session account labels — use --from-account / --to-account for accounts.

Default providers queried by swap quote and usable by swap execute: changelly, changelly_v2, cic, cic_v2, exodus, lifi, nearintents, okx, oneinch, swapsxyz, uniswap, velora. Some are CEX/aggregators run through the legacy Exchange-app pipeline; the DEX providers (uniswap, oneinch, velora, okx) execute in the partner's embedded coin app — see swap execute — DEX providers.

Accounts: --from-account and --to-account accept a session label only; the CLI resolves a fresh receive address from the account like receive.

pnpm --silent wallet-cli start swap quote --from ethereum --to bitcoin --amount 0.1 --from-account ethereum-1 --to-account bitcoin-native-1
pnpm --silent wallet-cli start swap quote -f ethereum -t bitcoin --amount 0.1 --from-account ethereum-1 --to-account bitcoin-native-1 --output json

Required: --from, --to, --from-account, --to-account, --amount.

swap execute

Currencies: --from / -f and --to / -t are Ledger currency IDs (same as swap quote): native assets or tokens on an allowed parent chain. They must match the asset of the source --account and of --to-account respectively.

Providers: Valid --provider values are changelly, changelly_v2, cic, cic_v2, exodus, lifi, nearintents, okx, oneinch, swapsxyz, uniswap, velora. Aliases: changelly → changelly_v2, 1inch → oneinch. Use the provider id shown on the quote line you pick from swap quote.

DEX providers (uniswap, oneinch, velora, okx): these run end-to-end in the partner's embedded coin app on the device (via the Device Intent Executor), not the legacy Exchange app. The flow re-fetches a quote for the chosen provider, then drives an on-device approval + swap sequence (sign-approval / sign-permit2 / sign-swap / broadcast), switching device apps as needed — confirm each Open <app> and signing prompt on the device.

• EVM only. DEX execution requires an EVM source account (e.g. ethereum); a non-EVM --account falls through to the legacy pipeline.
• RFQ quotes are not supported in the CLI. If the picked quote resolves to an RFQ plan (rfq-order / approval-then-rfq-order), the embedded flow is skipped and execution falls back to the legacy Exchange-app pipeline (you'll see a falling back to legacy Exchange-app pipeline progress line).

All other providers (changelly, cic, exodus, nearintents, swapsxyz, lifi, …) run the legacy Exchange-app pipeline (nonce → payload → complete exchange → sign/broadcast).

Fee strategy: --fee-strategy accepts slow, medium (default), or fast. On the legacy pipeline it sets the refund-chain transaction fee.

pnpm --silent wallet-cli start swap execute --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1
pnpm --silent wallet-cli start swap execute -f ethereum -t bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1 --fee-strategy fast
pnpm --silent wallet-cli start swap execute --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1 --output json
# DEX (embedded coin app): EVM-only, source and destination on an EVM chain
pnpm --silent wallet-cli start swap execute --from ethereum --to ethereum/erc20/usd_tether__erc20_ --account ethereum-1 --to-account ethereum-1 --provider uniswap --amount 0.1

Required flags: --from, --to, --account, --to-account, --provider, --amount. Use a --provider value that matches the provider id on the quote line you pick from swap quote.

swap status

pnpm --silent wallet-cli start swap status --swap-id <swapId> --provider changelly
pnpm --silent wallet-cli start swap status --swap-id <swapId> --provider changelly --output json

Required flags: --swap-id, --provider

assets token / token-by-id

Resolve token metadata from the cryptoassets store. No device, no session.

pnpm --silent wallet-cli start assets token ethereum 0xdac17f958d2ee523a2206206994597c13d831ec7
pnpm --silent wallet-cli start assets token-by-id ethereum/erc20/usd_tether__erc20_

Use token when you have the contract address; use token-by-id when you have the id. Exits non-zero if not found.

For non-EVM chains pass --identifier.

The id printed here is the same id accepted by swap quote --from / --to and swap execute --from / --to.

ring — Ledger Key Ring (LKRP)

Trustless, hardware-rooted encryption for files and text. The key ring is provisioned once on your Ledger via the Ledger Sync app; afterwards encrypt/decrypt run without the device — keys derive deterministically via HKDF-SHA256 from the LKRP-shared root and never leave AES-256-GCM. encrypt/decrypt still call the LKRP backend to restore the trustchain on each invocation, so network access is required. The ring is recoverable from your seed on any new machine.

# One-time provisioning (device required). Password comes from WALLET_PASS in the environment (see below); name the machine with --name.
pnpm --silent wallet-cli start ring init
pnpm --silent wallet-cli start ring init --name my-laptop

# File round-trip (no device after init):
pnpm --silent wallet-cli start ring encrypt --key my-oss-project -i .publish-tokens -o .publish-tokens.enc
pnpm --silent wallet-cli start ring decrypt --key my-oss-project -i .publish-tokens.enc -o .publish-tokens

# Text via stdin/stdout (clipboard pattern):
pbpaste | pnpm --silent wallet-cli start ring encrypt --key personal-notes | pbcopy
pbpaste | pnpm --silent wallet-cli start ring decrypt --key personal-notes | pbcopy

# List the keys this machine has used; tear down the ring:
pnpm --silent wallet-cli start ring keys
pnpm --silent wallet-cli start ring destroy

Always provision with a password. The ring must be protected by a password. The user provides it via WALLET_PASS in the environment before running ring init (see Non-TTY password injection) — the agent never provisions a ring without one.

Decrypted output is sensitive. ring decrypt emits secrets — never print them to the terminal, cat a decrypted file, or otherwise surface the decrypted contents, since they land in the agent transcript, logs, and scrollback. Pipe decrypt straight to its destination (a file via -o, another process, or the clipboard as shown above) or capture it into an env var; avoid --output/logging sinks that could echo it back.

--key <name> derives a per-name AES-256-GCM key; matching name at decrypt time is mandatory. Names are free-form (max 253 chars, no whitespace) — common patterns: project slugs (my-oss-project), env tags (openClaw-prod), notebooks (personal-notes).

Non-TTY (CI / agentic) password injection: the ring commands read the password from the WALLET_PASS env var when there is no TTY. The password itself must be provisioned by the developer/user (exported in the environment or stored in the OS keychain) — the agent never chooses, types, or otherwise handles the secret value; it only references what the user has already provisioned.

• Never write the password literally into a command (e.g. WALLET_PASS=hunter2 wallet-cli …, or via a flag). A literal leaks into shell history, ps output, CI logs, and — when an agent runs the command — the agent transcript. This applies to throwaway/test passwords too: make it a habit, because the same command shape is reused with a real secret.
• Always inject via command substitution so the secret never appears in the command text you type:
  • macOS : WALLET_PASS=$(security find-generic-password -a default -s ledger-wallet-cli -w) wallet-cli ring encrypt …
  • Linux : WALLET_PASS=$(secret-tool lookup service ledger-wallet-cli account default) wallet-cli ring encrypt …
• Agents must not handle the secret at all. Ask the user to store the password once in their OS keychain, then reference only the $(…) substitution. If a test or ring init needs a password, store a throwaway value in the keychain first (security add-generic-password -a default -s ledger-wallet-cli -w) and inject it the same way — never type the literal into a tool call.
• Even via substitution the value lives in the child process environment (readable via ps eww by the same user) — acceptable, but prefer the keychain form and avoid --output json sinks or logs that could echo it back.

Rotation limitation: the domain key derives from the ring's wallet-sync encryption key, which the LKRP protocol rotates when a ring member is removed. After a rotation, data encrypted before it can no longer be decrypted (decrypt fails with a "wrong key name, corrupted data, or the Ledger Key Ring rotated" error, and the CLI prints a ⚠ Ledger Key Ring rotated warning). Re-encrypt the affected data under the new ring after a member is removed. ring destroy aborts (no changes) if you enter a wrong password, and also if WALLET_PASS is set but empty (a failed keychain lookup) — this is treated as a mistake, not a skip, so it never orphans the remote ring. To intentionally skip the remote teardown and wipe only local credentials, press Enter at the interactive password prompt.

Agent Intent

Separate trust model from ring. The agent is a software-only LKRP member: it joins its own Agent Intent (App-18) Trustchain and is granted access to the user's Ledger Sync (App-16) stream, but it never opens the device and never receives ring's (App-17) domain keys.

Agent Intent enrolls a remote agent (a bot proposing transaction intents for human review) as a software identity local to this machine — no device required for enroll/recover/list/show/sync. Each profile gets its own secp256k1 keypair; the private key never leaves the OS keychain and is never printed, logged, or included in any command's output (human or --output json).

# Create a pending profile, print its signed enrollment URL + fingerprint, then BLOCK until the
# human approves in the Agent Intent frontend (default environment: production):
pnpm --silent wallet-cli start agent-intent enroll --profile my-bot --name "My Bot" --source claude-code
pnpm --silent wallet-cli start agent-intent enroll --profile my-bot --name "My Bot" --source other \
  --environment staging --expires-in 2h

# Re-enroll an enrolled profile's existing key into its previous Trustchain, then
# BLOCK until approved (environment/keycloak come from the profile):
pnpm --silent wallet-cli start agent-intent recover --profile my-bot

# List/inspect local profiles (never reveals the secret key):
pnpm --silent wallet-cli start agent-intent list
pnpm --silent wallet-cli start agent-intent show --profile my-bot

# Import the Ledger Sync accounts the agent was granted into the session (explicit, never automatic):
pnpm --silent wallet-cli start agent-intent sync --profile my-bot
pnpm --silent wallet-cli start agent-intent sync --profile my-bot --output json

Always pass --source. It is the runtime or harness the agent runs in (not its model provider): openclaw, hermes, claude-code, codex, cursor, muse, grok-bot, or other when none matches. Omitting it defaults to other. The frontend shows it as the agent's source; never pass a value outside this list.

One blocking command, no copy/paste. enroll prints the URL first (with --output json: an enrollment-pending NDJSON event), then waits on an encrypted Trustchain relay channel bound into the signed request. The frontend delivers the completion over that channel; there is no complete command and no manual JSON fallback. Keep the process running until it prints the final enrolled result (json: status: "success", enrolled: true, trustchainId, accountAccessEnvironment). The wait is bounded by --expires-in (default 30m).

Nothing is trusted from the relay alone. Before saving, enroll proves the completion: the agent key must obtain an App-18 access token for the claimed Trustchain (Keycloak), and must authenticate to the claimed App-16 stream with exactly the expected permission. Only then are trustchainId and the (non-secret) accountAccess references written to the profile.

On timeout, Ctrl+C, or a failed check the profile stays pending (and later expired) and cannot be resumed — start a fresh enrollment with a new --profile id.

Recovery reuses the same key. recover --profile <id> signs a recovery request for the profile's existing key and Trustchain (no new key, accountAccess untouched), then waits on the relay exactly like enroll (json: a recovery-pending event, then status: "success", recovered: true, trustchainId). Any enrolled profile whose keychain key matches the recorded public key can be recovered, whatever its --source. The completion must name the same agent key, the same signed request and the same Trustchain, and the agent key must obtain an App-18 token for it (App-16 is not re-checked). While it waits, list/show report recovering; on timeout, Ctrl+C, or a failed check the marker is cleared and the profile stays enrolled with its previous data — re-run recover to retry.

Fingerprint is the safety check. enroll prints a public-key fingerprint alongside the enrollment URL, and show prints the same fingerprint for any profile afterwards — compare it against what the Agent Intent frontend/device displays before approving. A mismatched fingerprint means the enrollment request was tampered with or sent to the wrong agent.

Duplicate protection: enroll refuses to reuse a --profile id already recorded in the session, and separately refuses if a keychain entry for that id exists without a matching session record (an inconsistent state you must clear manually before re-enrolling under the same id).

Keychain required: enroll needs a working OS keychain — macOS Keychain, Windows Credential Manager, or on Linux a running Secret Service provider (e.g. gnome-keyring or KeePassXC) with an unlocked collection. Without one (headless Linux, containers, some CI runners) enroll fails with Could not store the agent's secret key in the OS keychain (…) and saves nothing — fix the keychain and re-run the same command; there is no file-based fallback by design.

Environment isolation: each profile records the environment (staging/production) it was enrolled against. A completion whose accountAccess.environment doesn't match is rejected, so a profile enrolled for staging can never end up holding a production Trustchain ID. --bff-url and --keycloak-url override that environment's defaults (http(s) only, no user:pass@).

Status is derived, not stored: list/show compute pending / enrolled / recovering / expired from trustchainId, enrollmentExpiresAt and any unexpired recovery marker, and show the granted account access (environment + App-16 application path) once enrolled.