💫 What Is lncli?

lncli is the command line tool that comes with LND (Lightning Network Daemon). It describes itself as the:

control plane for your Lightning Network Daemon (lnd)

That's a fancy way of saying: lnd is the program that actually runs your Lightning node, and lncli is how you tell it what to do.

The two-program setup

This trips up a lot of new node runners, so let's be very clear about it.

• lnd is a daemon. It runs continuously in the background, stays connected to peers, watches the blockchain, forwards payments, and keeps your channels alive. You start it once and leave it running.
• lncli is a client. It runs for a fraction of a second, sends one request to lnd, prints the answer, and exits.

lncli does not "do" Lightning. It just asks lnd to do Lightning. Under the hood, every lncli command is a gRPC call to your running lnd process — the exact same API that node dashboards like LNDG use.

That has a useful consequence: anything you can see in a GUI, you can see with lncli. And anything lncli can do, an app can do too.

Why bother with the command line?

Because it is the most direct, most reliable, and best-documented way to operate your node.

GUIs are lovely for browsing. But when it comes to actions — opening channels, closing channels, stopping the node, paying invoices — we recommend lncli, for a few reasons:

1. It tells you exactly what happened. Errors come back as real error messages from lnd, not a red icon.
2. It has built-in help. Every command explains its own flags (more on this below).
3. It matches the documentation. LND release notes, GitHub issues, and every guide on the internet are written in terms of lncli commands.
4. Nothing is hidden. A GUI decides which options to expose. lncli exposes all of them.

If you're running your node with our Docker setup, you get to an lncli prompt by running ./exec-lncli.sh, which drops you into a command line inside the running LND container.

Your first two commands

Once you're at a prompt where lncli works, try these:

lncli getinfo

This returns basic information about your node: its public key, alias, version, block height, how many peers you're connected to, and how many channels are active. If getinfo works, your node is alive and lncli can talk to it.

lncli walletbalance

This shows your on-chain balance — the bitcoin you could use to open channels. Note that this is not your channel balance. For that, you want lncli channelbalance.

The most useful trick: --help

You do not need to memorize lncli. You need to remember one flag.

lncli --help

...lists every command. And:

lncli newaddress --help

...explains one specific command, including all of its options. This works for every command in the tool, and it always reflects the version of LND you actually have installed. It is faster and more accurate than searching the web.

A tour of the commands

Here is the full command list from lncli --help, as of LND v0.21.2-beta. You will not need most of these. But it's genuinely useful to skim the list once, just so you know what exists.

Top level

Command	What it does
getinfo	Returns basic information related to the active daemon.
getrecoveryinfo	Display information about an ongoing recovery attempt.
debuglevel	Set the debug level.
stop	Stop and shutdown the daemon.
version	Display lncli and lnd version info.
help, h	Shows a list of commands or help for one command.

tip

lncli stop is the correct way to shut down your node. Never just kill the process or pull the plug — see starting and stopping LND.

Channels

This is the group you'll live in as a node runner.

Command	What it does
openchannel	Open a channel to a node or an existing peer.
batchopenchannel	Open multiple channels to existing peers in a single transaction.
closechannel	Close an existing channel.
closeallchannels	Close all existing channels.
abandonchannel	Abandons an existing channel.
channelbalance	Returns the sum of the total available channel balance across all open channels.
pendingchannels	Display information pertaining to pending channels.
listchannels	List all open channels.
closedchannels	List all closed channels.
getnetworkinfo	Get statistical information about the current state of the network.
feereport	Display the current fee policies of all active channels.
updatechanpolicy	Update the channel policy for all channels, or a single channel.
exportchanbackup	Obtain a static channel back up for selected channels, or all known channels.
verifychanbackup	Verify an existing channel backup.
restorechanbackup	Restore an existing single or multi-channel static channel backup.
listaliases	List all aliases.
updatechanstatus	Set the status of an existing channel on the network.

Payments

Command	What it does
sendpayment	Send a payment over lightning.
payinvoice	Pay an invoice over lightning.
sendtoroute	Send a payment over a predefined route.
listpayments	List all outgoing payments.
queryroutes	Query a route to a destination.
fwdinghistory	Query the history of all forwarded HTLCs.
deletefwdhistory	Delete old forwarding history for privacy.
trackpayment	Track progress of an existing payment.
deletepayments	Delete a single or multiple payments from the database.
estimateroutefee	Estimate routing fees based on a destination or an invoice.
buildroute	Build a route from a list of hop pubkeys.

Invoices

Command	What it does
addinvoice	Add a new invoice.
lookupinvoice	Lookup an existing invoice by its payment hash.
listinvoices	List all invoices currently stored within the database.
deletecanceledinvoice	Delete a canceled invoice from the database.
decodepayreq	Decode a payment request.
cancelinvoice	Cancels a (hold) invoice.
addholdinvoice	Add a new hold invoice.
settleinvoice	Reveal a preimage and use it to settle the corresponding invoice.

On-chain

Command	What it does
estimatefee	Get fee estimates for sending bitcoin on-chain to multiple addresses.
sendmany	Send bitcoin on-chain to multiple addresses.
sendcoins	Send bitcoin on-chain to an address.
listunspent	List utxos available for spending.
listchaintxns	List transactions from the wallet.
chain	Interact with the bitcoin blockchain.

Wallet

Command	What it does
newaddress	Generates a new address.
walletbalance	Compute and display the wallet's current balance.
signmessage	Sign a message with the node's private key.
verifymessage	Verify a message signed with the signature.
wallet	Interact with the wallet.

Startup

These are the commands you use before your wallet is unlocked — that is, when lnd is running but not yet usable.

Command	What it does
create	Initialize a wallet when starting lnd for the first time.
createwatchonly	Initialize a watch-only wallet after starting lnd for the first time.
unlock	Unlock an encrypted wallet at startup.
changepassword	Change an encrypted wallet's password at startup.
state	Get the current state of the wallet and RPC.

Peers

Command	What it does
connect	Connect to a remote lightning peer.
disconnect	Disconnect a remote lightning peer identified by public key.
listpeers	List all active, currently connected peers.
sendcustom	Send a custom p2p wire message to a peer.
subscribecustom	Subscribe to incoming custom p2p wire messages from all peers.
peers	Interacts with the other nodes of the network.

Graph

Command	What it does
describegraph	Describe the network graph.
getnodemetrics	Get node metrics.
getchaninfo	Get the state of a channel.
getnodeinfo	Get information on a specific node.

caution

lncli describegraph dumps the entire Lightning Network graph. That is a very large amount of JSON. Pipe it somewhere or filter it — don't just let it scroll past.

Macaroons

Macaroons are LND's authentication credentials. These commands let you create limited-permission credentials instead of handing out full admin access.

Command	What it does
bakemacaroon	Bakes a new macaroon with the provided list of permissions and restrictions.
listmacaroonids	List all macaroons root key IDs in use.
deletemacaroonid	Delete a specific macaroon ID.
listpermissions	Lists all RPC method URIs and the macaroon permissions they require to be invoked.
printmacaroon	Print the content of a macaroon in a human readable format.
constrainmacaroon	Adds one or more restriction(s) to an existing macaroon.

Mission Control

Mission Control is LND's memory of which routes have worked and which have failed. It's what makes your second payment attempt smarter than your first.

Command	What it does
querymc	Query the internal mission control state.
importmc	Import a result to the internal mission control state.
loadmc	Load mission control results from a file produced by querymc, with the option to shift timestamps. Not persisted across restarts.
resetmc	Reset internal mission control state.
getmccfg	Display mission control's config.
setmccfg	Set mission control's config.

Watchtower

Command	What it does
tower	Interact with the watchtower.
wtclient	Interact with the watchtower client.

See connect to a watchtower for how to actually use these.

Debug

Command	What it does
getdebuginfo	Returns debug information related to the active daemon.
encryptdebugpackage	Collects a package of debug information and encrypts it.
decryptdebugpackage	Decrypts a package of debug information.

Everything else

Command	What it does
autopilot	Interact with a running autopilot.
neutrino	Interact with a running neutrino instance.
profile	Create and manage lncli profiles.

Global options

These flags go before the command name, and they control how lncli connects to lnd — not what it does once connected.

lncli --network testnet --rpcserver localhost:10011 getinfo

Flag	Purpose
--rpcserver	The host:port of the LN daemon. Default: localhost:10009
--lnddir	The path to lnd's base directory.
--socksproxy	The host:port of a SOCKS proxy to connect through.
--tlscertpath	The path to lnd's TLS certificate.
--chain, -c	The chain lnd is running on, e.g. bitcoin.
--network, -n	mainnet, testnet, testnet4, regtest, signet, or simnet. Default: mainnet
--no-macaroons	Disable macaroon authentication.
--macaroonpath	The path to the macaroon file.
--macaroontimeout	Anti-replay macaroon validity time in seconds. Default: 60
--macaroonip	If set, lock the macaroon to a specific IP address.
--profile, -p	Use a specific profile instead of command line parameters.
--macfromjar	Use a specific macaroon from the profile's macaroon jar.
--metadata	Append a "key:value" pair to the outgoing request context. May be repeated.
--help, -h	Show help.
--version, -v	Print the version.

Most of these have a matching environment variable (LNCLI_RPCSERVER, LNCLI_NETWORK, LNCLI_MACAROONPATH, and so on), which is handy in scripts and Docker setups.

note

If you run more than one node — say, a mainnet node and a testnet node on the same machine — the --network and --rpcserver flags are how you make sure you're talking to the one you meant. Getting this wrong is a classic way to have a confusing afternoon.

Common gotchas

"connection refused" or "unable to connect to RPC server." lnd isn't running, or it's not listening where lncli is looking. Check that the daemon is up, and check your --rpcserver value.

"wallet locked, unlock it to enable full RPC access." lnd is running, but the wallet is encrypted and hasn't been unlocked since the last restart. Run lncli unlock.

"unable to read macaroon path." lncli found the daemon but has no credentials. Point --macaroonpath at the right admin.macaroon, or check --lnddir.

Everything works, but the numbers look wrong. Make sure you understand which balance you're looking at. walletbalance is on-chain. channelbalance is Lightning. They are completely separate pools of money.

If you're building on the LND API, prototype with lncli first

lncli is not just an operator tool. It is also the fastest way to learn the LND API, which is very powerful and lets you build real applications on top of your node.

Remember: lncli is an API client. Every command maps to an RPC in that documentation. lncli addinvoice is AddInvoice. lncli listchannels is ListChannels. lncli payinvoice is SendPaymentV2. Same calls, same fields, same responses.

So when you're writing code, the workflow that saves the most time is:

1. Run the operation with lncli first. Get it working by hand, on the command line, with real values.
2. Look at the actual response. lncli prints raw JSON. That is precisely the shape your code will receive.
3. Then write the code, against a response you have already seen with your own eyes.

This matters more than it sounds like it should. When you skip step 1 and something fails, you have no idea whether the bug is in your gRPC setup, your macaroon, your parameters, or your understanding of the call. When you've already run it with lncli, you know the operation itself is fine — so the problem is in your client, and you've cut the search space in half.

It also quietly answers a lot of questions the docs don't: which fields are actually populated in practice, what an empty result looks like, how long a call takes, and what the error message really says when you get it wrong.

tip

Do your first experiments on testnet or signet, not mainnet. Use --network testnet and point --rpcserver at your test node. Lightning API calls move real money, and lncli will happily let you do that at 2am.

Two more habits worth picking up early:

• lncli listpermissions shows every RPC method URI and the macaroon permissions it requires. This is how you figure out the minimum permissions your app needs, so you can bakemacaroon a limited credential instead of shipping admin.macaroon.
• --help beats the docs for your version. The API docs cover the current release. lncli <command> --help covers the release you're actually running.

Where to go next

• Set up LND with Docker — get a node running, and get to an lncli prompt.
• Starting and stopping LND — how to shut down without hurting anything.
• Depositing funds onto your node — lncli newaddress in anger.
• How to open a channel — lncli openchannel, explained.
• How to send a payment — lncli payinvoice, explained.

And when in doubt: lncli --help.