wavecli

wavecli is the command-line client for the wallet daemon (waved). It issues gRPC calls to a running daemon and prints command-appropriate human or machine-readable output. The everyday surface is a small set of wallet verbs (create, unlock, send, recv, activity, balance, exit); a handful of daemon-introspection commands and advanced subtrees round it out.

This slice documents the CLI itself. If you are integrating over gRPC or REST from your own code, see the API reference for the underlying WalletService and WalletInspectionService.

Connecting

Every command talks to a running daemon over gRPC. The connection is configured with a set of persistent flags, available on every command:

Flag Default Description
--rpcserver localhost:10029 Daemon gRPC server address (host:port).
--network mainnet Bitcoin network used to resolve the default TLS certificate and macaroon paths.
--tlscertpath (none) Path to the daemon TLS certificate.
--macaroonpath (none) Path to the daemon RPC macaroon.
--no-tls false Disable TLS for the daemon connection (development and regtest).
--no-macaroons false Disable macaroon authentication for the daemon connection (development and regtest).
--timeout 30s Maximum duration for each daemon RPC. 0 disables the deadline.
--json false Emit machine-readable JSON output. A shorthand for --format json on commands with a --format selector.
--no-input false Never prompt or implicitly consume stdin. Setting the CI=true environment variable has the same prompt-suppression effect.
--request-json (none) Raw JSON request payload that maps directly to the RPC request proto. When set, the command’s bespoke flags are ignored.

The --request-json flag is the raw-request escape hatch: pass a JSON object shaped like the method’s request proto and it is sent verbatim, so an agent can drive any command from a single serialized payload instead of assembling flags. It is distinct from the --json output selector.

Flags are spelled in kebab-case, but every flag also accepts the snake_case spelling of the same name (--max_fee resolves to --max-fee), so a name copied from an RPC field or a daemon log works unchanged.

Ctrl-C (and SIGTERM) cancel the running command cleanly: in-flight RPCs are cancelled, and a command interrupted while waiting on settlement reports a CANCELED envelope with the last observed phase.

Output conventions

Successful commands print a structured JSON object to stdout. Proto-backed responses are marshaled with proto field names (snake_case) and unpopulated fields emitted, so the shape is stable across calls. Confirmation prompts, the generated seed on create, and progress lines go to stderr, keeping stdout a clean JSON stream for pipelines. The one human-oriented exception is activity, which prints its table (and next-page hint) to stdout by default; pass --format json there when scripting.

On failure the command writes a JSON error envelope to stderr and exits non-zero:

{
  "error": {
    "code": "WALLET_LOCKED",
    "message": "wallet is locked; run `wavecli unlock`",
    "details": "",
    "retryable": false
  }
}

code is a stable machine-readable string (for example INVALID_ARGS, WALLET_LOCKED, NOT_FOUND, METHOD_NOT_FOUND, CONFIRMATION_REQUIRED, CANCELED), message is a human-facing description, and details carries optional diagnostic context (such as the wrapping RPC call chain). retryable reports whether a blind retry is safe: codes that can fire after a fund-moving RPC was already accepted (DEADLINE_EXCEEDED, ABORTED, WAIT_TIMEOUT) report false, and where the CLI knows a concrete next step it adds a remediation string (for example “check state before retrying”).

Exit codes

The exit code lets an agent or shell branch on the failure category without parsing prose. The codes are semantic:

Exit code Name Meaning
0 success The command completed. Set implicitly when the command returns without error.
1 generic error Catch-all failure not covered by a more specific code.
2 invalid arguments The invocation was rejected before reaching the daemon: a missing required flag, a malformed outpoint, conflicting --offchain/--onchain, and similar.
3 auth failure The daemon rejected the call as unauthenticated or not permitted (a missing or invalid macaroon), or the wallet is not ready for the verb (locked, not yet created, or still syncing, reported as WALLET_LOCKED and friends). A wrong password on unlock reports 2 instead; see the mapping below.
4 not found A queried resource does not exist on the daemon (an unknown round id, a missing exit job).
5 confirmation required The command is valid, but a fund-moving action needs explicit --yes (or --force) approval in a non-interactive environment.

Daemon-side gRPC failures are mapped onto the same table: InvalidArgument, OutOfRange, and FailedPrecondition map to exit code 2; Unauthenticated and PermissionDenied to 3; NotFound to 4; everything else to 1. The one carve-out is the wallet lifecycle preconditions (locked, not created, syncing): they arrive as FailedPrecondition but exit 3, agreeing with the WALLET_LOCKED envelope they emit.

Command index

Wallet

The everyday verbs. They call WalletService (and, for inspection, WalletInspectionService) and cross-link to the matching API reference page.

Command What it does
create Create a new wallet from a fresh seed.
unlock Unlock an existing wallet.
send Send a Lightning or on-chain payment.
recv Receive a payment: a Lightning invoice or a boarding address.
activity Show wallet activity, and inspect a single entry.
balance Display the unified wallet balance.
exit Cooperatively exit a VTXO, or start a forced unroll.
wallet-sweep Sweep the backing wallet to a destination address.

Daemon

Introspection and integration surfaces that live at the root.

Command What it does
getinfo Display daemon status information.
schema Dump machine-readable method schemas as JSON.
mcp Run a Model Context Protocol server over stdio.

Advanced

Power-user subtrees over the raw daemon RPC. Most integrations never need these.

Command What it does
ark Low-level Ark protocol commands (VTXOs, rounds, OOR, boarding, sweeps, fees).
recovery Manage daemon-owned vHTLC recovery rows.
dev Generated low-level access to every daemon gRPC method.