CoalesceCLI Reference
Every coalesce-node subcommand, prompt command, and environment variable.
Run coalesce-node <cmd> -h for a command's full flag list. This page covers what each one is
for and when to reach for it.
CLI subcommands
These are invoked as coalesce-node <cmd> ... from your shell.
| Command | What it does |
|---|---|
bootstrap | Set up a cluster over the network and continue straight into running it, with no manual file passing and no separate run step. Key flags: -dir <dir>, -addr <host:port>, -peers <addr0,addr1,...> (known members) or -discover -want <n> [-room <name>] (find strangers via public Nostr relays), -quorum <N>, -balance <sats>, plus -wallet, -enforce, -verbose, -auto-root-depth, -auto-root-fallback (same as run). Every connection is authenticated with a pubkey-pinned challenge-response. Recommended for real, multi-operator setups. |
identity | Generate your own identity key locally. -dir <dir>, -addr <host:port> (your advertised address). Manual alternative to bootstrap, pairs with assemble. |
assemble | Assemble a cluster from public identity bundles produced by identity. -dir <dir>, -bundles <b0.json,b1.json,...>, -quorum <N> (default: supermajority), -balance <sats>. No private key material is ever read or written. |
init | Generate cluster configs in one step. -distributed (shareless), -hosts, -nodes, -base-port, -balance. Quicker than bootstrap/identity+assemble, but the operator running it transiently holds every participant's identity private key. |
run | Run a node. -config <file> (required), -wallet <name> (enables funding), -enforce (self-protection), -auto-root-depth <N> (override the automatic-checkpoint threshold; 0 disables it), -auto-root-fallback <dur> (override the fallback-proposer timing), -verbose (print internal protocol diagnostics). |
fund / close | Coordinator-run funding/closing: one machine holds all wallets, for demos/testing only. Prefer dfund/coopclose (at the prompt) for real use. |
Prompt commands
Once a node is running (via bootstrap or run), type these at its interactive prompt.
| Command | What it does |
|---|---|
keygen | Generate the group key distributed-ly (shareless clusters). Auto-restarts the node when done. |
attach-wallet <name> | Wire up a bitcoind wallet for dfund, live, if the node wasn't started with -wallet. No restart needed. |
dfund <amountSat> [fee] [address] | Commit your own contribution (any amount, in sats) from your own wallet; optionally choose your close payout destination. Auto-restarts once your deposit confirms. |
send <peer> <sats> | Pay another member. Over-balance sends are refused upfront with exact committed/pending/available figures. |
propose | Finalize a checkpoint (locks in payments); usually automatic, see Concepts: Checkpoints. |
bal | Show balances. On a closed cluster, shows the final payouts paid by the close transaction instead. |
coopclose [fee] | Cooperatively close: pays each member out to their chosen settlement address, printing the full settlement before broadcasting. Refuses on an already-closed cluster. |
watch <clusterID> <txid> <vout> | Watch a funding output on-chain. |
quit | Shut down (Ctrl-C also works). |
Environment variables
| Variable | Meaning |
|---|---|
COALESCE_BTC_NET | signet (or regtest) |
COALESCE_BTC_HOST | your bitcoind RPC host, e.g. localhost:38332 |
COALESCE_BTC_COOKIE | override the cookie path (default: the standard signet cookie) |
COALESCE_BTC_USER / COALESCE_BTC_PASS | RPC user/pass (only if you don't use cookie auth) |
COALESCE_RELAY_PORT | pin the relay listener to a fixed port instead of a random one |
COALESCE_INSTALL_DIR | override where the install script places the coalesce-node binary |