wavecli

wavecli is the command-line client for the wallet daemon (waved). It issues gRPC calls to a running daemon and prints structured JSON to stdout, suitable for both human and agent consumption. 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).
--json (none) Raw JSON request payload that maps directly to the RPC request proto. When set, the command’s bespoke flags are ignored.

The --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 per-command --format json output selector.

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. Human-oriented views (the activity table, confirmation prompts, the generated seed on create) and progress lines go to stderr, keeping stdout a clean JSON stream for pipelines.

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": ""
  }
}

code is a stable machine-readable string (for example INVALID_ARGS, WALLET_LOCKED, NOT_FOUND, METHOD_NOT_FOUND, DRY_RUN_OK), message is a human-facing description, and details carries optional diagnostic context (such as the wrapping RPC call chain).

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 Wallet authentication failed: a wrong password, or a locked wallet on a verb that requires it.
4 not found A queried resource does not exist on the daemon (an unknown round id, a missing exit job).
10 dry-run OK A --dry-run invocation passed all local validation; no RPC was dispatched.

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.

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.