- Node administration
- On-chain wallet management
- Channel management
- Lightning Payments
- Swaps
- Bookkeeping
- Tips and Tricks
- List all outgoing satoshis currently in channels
- List the total of your node's on-chain wallet outputs
- Show the routing fees your node has earned
- Calculate successful and failed payment forwards from last 100k attempts
- Calculate successful and failed payment forwards from last 10k attempts
- List PeerSwap channels and their balance scores
--network specifies which network your CLN will be running on. Options are mainnet, testnet, regtest, signet. This can also be configured in your node's config file.
lightningd --network <network>
Display an overview of your node, including public key, alias, number of channels and peers, the address you're announcing to the Lightning network, and more.
lightning-cli getinfo
Example output:
{
"id": "0288c9aae9cabe5bbb100789b56f5f91706457612d9bd447a838eec209a3c24afe",
"alias": "YELLOWIRON",
"color": "0288c9",
"num_peers": 2,
"num_pending_channels": 0,
"num_active_channels": 2,
"num_inactive_channels": 0,
"address": [],
"binding": [
{
"type": "ipv4",
"address": "0.0.0.0",
"port": 9736
}
],
"version": "v0.11.0.1-385-gbed0075",
"blockheight": 100830,
"network": "signet",
"msatoshi_fees_collected": 0,
"fees_collected_msat": "0msat",
"lightning-dir": "/home/user/.lightning/signet",
"our_features": {
"init": "088000080a69a2",
"node": "888000080a69a2",
"channel": "",
"invoice": "02000000024100"
}
}
Warning
Improperly backing up your CLN data could be catastrophic. Make sure you have at least a basic form of backups.
It's critical for the lightningd.sqlite3 database in your CLN data directory to be continually backed up as it contains the most up to date state for your payment channels. Restoring a backup with old incorrect state will cause problems. hsm_secret can be safely backed up once.
CLN provides extensive documentation for backing up critical data that your node creates.
Shut your node down for maintenance or other tasks.
lightning-cli stop
Use this to receive bitcoins that you can use later on for opening payment channels. Address type can be p2sh-segwit, bech32, or all which generates both at once.
lightning-cli newaddr <address type>
Use this when you're ready to send bitcoin back to cold storage or if you need to send a payment on-chain.
lightning-cli withdraw <destination address> <amount in satoshis>
Example:
lightning-cli withdraw tb1q75ggprm38sl6p8x532p8jcce9fxm442axs54dy 100000
Instead of making multiple individual transactions, use this to create a transaction paying many different addresses at once.
lightning-cli multiwithdraw {address1: amount},{address2: amount}, ...
Example:
lightning-cli multiwithdraw "[{\"tb1q75ggprm38sl6p8x532p8jcce9fxm442axs54dy\": 1000000}, {\"tb1qykpzvmukjlew3v3u5z5q346xkvetkpmx4ne3pq\": 2000000}]"
lightning-cli listtransactions
lightning-cli withdraw -k destination=<address> satoshi=<use_any_amount> feerate=<fee in satoshis>perkb minconf=0 utxos='["txid:index"]'
Example:
lightning-cli withdraw -k destination=bc1q7tfayt5urfy9sulu9wcjn3hm4tj0vxsntupz3a satoshi=1000000 feerate=80000perkb minconf=0 utxos='["9245a9fc09ada2b1709d6f83ed2fa0875c91996a4c81eb6a03e84946f13c1042:0"]'
Connect your CLN node to a Lightning peer to begin downloading gossip data and in preparation of opening a payment channel.
lightning-cli connect <node id>
Example:
lightning-cli connect 0288c9aae9cabe5bbb100789b56f5f91706457612d9bd447a838eec209a3c24afe
lightning-cli disconnect <node id>
Occasionally you may need to force your CLN node to disconnect from a peer due to a bug between Lightning implementations or other reasons. Simply pass true to the disconnect after the node id to force a disconnect. CLN will then automatically try to reconnect.
lightning-cli disconnect <node id> true
lightning-cli fundchannel
lightning-cli multifundchannel
Attempt to coordinate a mutual channel close with the specified peer.
lightning-cli close <peer id>
Warning: Force closing a channel will lock up your on-chain funds for a period of time.
Broadcast a unilateral close transaction on-chain. The third argument is the number of seconds your CLN node will wait before force closing. The default is two days (172800 seconds).
lightning-cli close <peer id> <n seconds to wait before unilaterally closing>
When will funds be available after a unilateral close? credit: Warren Togami
Say your peer has been offline for 2+ weeks and you want to unilateral close the channel. The CSV timeout after which the funds are available to claim is typically 144 blocks for CLN. LND can be up to 2016 blocks depending on the channel capacity.
$ lightning-cli listpeers
# Find the txid of the unilateral close transaction then scroll down a bit.
"status": [
"CHANNELD_NORMAL:Reconnected, and reestablished.",
"ONCHAIN:Tracking our own unilateral close",
"ONCHAIN:3 outputs unresolved: in 139 blocks will spend DELAYED_OUTPUT_TO_US (53206ed042255fb0fae53c1fd0805832ff80869383cbddec1074965eaf3d7888:0) using OUR_DELAYED_RETURN_TO_WALLET"
],
Note: If
--experimental-offersis enabled,paycan also pay BOLT12 offers
Attempt to pay a BOLT11 invoice.
lightning-cli pay
lightning-cli sendpay
lightning-cli decode <BOLT11 or BOLT12 string>
lightning-cli invoice
This is useful for keeping track of the invoices you've created and seeing which ones have been paid or not.
lightning-cli listinvoices
BOLT12 is a proposed new method for payments on the Lightning network that provides a list of improvements over BOLT11 invoices. Read more at bolt12.org
lightning-cli offer
lightning-cli listoffers
lightning-cli getroute
Lightning payment channels periodically need to be rebalanced in order for payments to route successfully. There are a few ways to balance a channel ranging from circular payments within the Lightning network itself, to swapping on-chain bitcoin with off-chain Lightning bitcoin, or even swapping off-chain Lightning bitcoin with off-chain Liquid bitcoin (L-BTC) on the Liquid Network.
PeerSwap is a CLN plugin and LND daemon that enables swapping.
PeerSwap is available for both CLN and LND implementations. Follow the install guide for CLN or LND.
Swap outs push sats to your peer, who in turn sends onchain coins back. This results in more inbound liquidity for that channel.
$ lightning-cli peerswap-swap-out <short channel id> <amount in sats> <asset, either btc or lbtc>
Swap ins push sats to your side of the channel, and you send onchain coins in exchange. This results in more outbound liquidity for that channel.
$ lightning-cli peerswap-swap-in <short channel id> <amount in sats> <asset, either btc or lbtc>
$ lightning-cli peerswap-lbtc-getbalance
$ lightning-cli peerswap-listpeers
$ lightning-cli peerswap-addpeer <pubkey>
New in CLN v0.12.0 is the bookkeeper plugin. This new plugin helps you keep track of how your satoshis are shuffled around in your open channels. Useful for accounting! The bookkeeper plugin refers to channels as "accounts" and forwarded payments, channel open / close activity, etc. are referred to as "events".
lightning-cli bkpr-listbalances
lightning-cli bkpr-listaccountevents <account>
lightning-cli bkpr-inspect <account>
lightning-cli bkpr-listincome
lightning-cli bkpr-dumpincomecsv <format>
lightning-cli bkpr-channelsapy <start time> <end time>
lightning-cli listfunds | jq '[.channels[].channel_sat] | add'
lightning-cli listfunds | jq '[.outputs[].value] | add'
lightning-cli getinfo | jq '.msatoshi_fees_collected / 1000'
Credit: fiatjaf
lightning-cli listforwards | jq '.forwards[-100000:] | map(.status) | reduce .[] as $status ({}; .[$status] = (.[$status] // 0) + 1)'
Credit: fiatjaf
lightning-cli listforwards | jq '.forwards[-10000:] | map(.status) | reduce .[] as $status ({}; .[$status] = (.[$status] // 0) + 1)'
Credit: tsjk
lightning-cli peerswap-listpeers | jq -r '[.[].channels[] | .balance_score += 100 * (1 - (2 * (.5 - (.local_balance / (.local_balance + .remote_balance))) | fabs))] | sort_by(.balance_score)'