balanceofsatoshis turns LND into a balance and rebalance command line

The problem bos solves: knowing where your node's sats sit

A Lightning node holds two balances that move in opposite directions, and both matter. One side is the local channel liquidity you can spend, the other is the remote balance locked in channels with peers, which is the liquidity that lets other people pay you. Node operators run into the same asymmetry constantly: a node earns well on the inbound side and runs dry on the outbound side, so payments fail even though the node looks busy in a dashboard. balanceofsatoshis, published as bos, exists to make that state legible from a terminal. The command set covers accounting breakdowns by category, a total balance that includes pending funds while excluding future commit fees, separate totals for inbound and outbound liquidity, charts of fees earned and paid, and a general activity report. It also covers the fix: commands to increase inbound or outbound liquidity and to rebalance funds between peers. The audience is the operator who already has an LND node running, because bos is a client for an existing node, not a node of its own.

How bos reaches the node: macaroons, a cert and a socket

The authentication model is the interesting part, because it explains both the security posture and the setup friction. By default bos expects tls.cert in the root of the default lnd directory and admin.macaroon in the network subdirectory of that same tree, so on macOS that means ~/Library/Application Support/Lnd/ and on Linux ~/.lnd/. The lookup order is deliberate: the project checks first for a mainnet macaroon and then for a testnet macaroon, which removes one common source of operator error where the wrong macaroon gets used against the wrong network. The macaroon is an admin macaroon, so anything bos can do is scoped by what that macaroon grants, which in practice means full node control. Credentials handling lives under test/ in the repository, and the package manifest shows the tool is built on ln-service and ln-accounting packages rather than speaking raw gRPC itself. That layering is the real alternative to hand rolling gRPC calls against LND: you give up low level control, and in exchange the accounting and rebalance logic is already written and maintained by someone else.

Installing bos with npm, and the Node version question

Installation is a global npm package and nothing more exotic. Node v20 or newer is required by the installation notes, though the package manifest declares a stricter floor with engines set to node >=22, so a Node 20 machine can install the package and still sit outside what the package itself declares as supported.

npm install -g balanceofsatoshis

If you would rather not install anything globally, the project points at npx, which fetches and runs the package on the spot. After installing, verify the binary is on your path by asking it for its version.

bos --version

That prints the currently installed version. If nothing comes back, the usual cause is that the global npm bin directory is not on your shell path rather than that the install failed. A list of available options and flags comes from the help command, and the same command accepts a command name for detail on one subcommand.

bos help

Reading the balance before changing anything

The fastest way to confirm that bos can reach your node is the balance command, which shows the total including pending funds while excluding future commit fees. That exclusion matters for anyone planning to spend the figure, since commit fees for open channels are deducted later. The liquidity commands give the split view: inbound-liquidity outputs the sum total of remote channel liquidity, which is the money peers hold on your side of the channels, and outbound-liquidity gives the matching sum of local channel liquidity.

bos balance
bos inbound-liquidity
bos outbound-liquidity

Run those three and you learn the shape of the node without changing anything. Peers lists channel connected peers, forwards gives a summarized version of peers you forwarded towards, and pending shows pending channels along with in flight HTLCs. The fee commands answer the profitability question, with charts of routing fees earned and paid, and chain fees paid reported separately because on chain spending is a different cost centre from Lightning routing. The accounting command groups transactions by category for a period view of where money moved, and the report command gives a general summary of node activity.

Rebalancing, and the paid community behind it

The commands that change state are the ones worth reading twice. There is a rebalance command that moves funds between peers, separate commands to increase inbound and outbound liquidity, and a command for enforcing rules on inbound channels. A probe command tests whether funds can be sent to a destination, and a pay command pays a payment request or offer while probing first, which lets you ask the question before committing the payment.

bos probe "payment_request/offer/public_key"
bos rebalance

Some of the operational depth is not in the open repository at all. The project describes a trade-secret command and a secret that gains access to a private Telegram group, and the linked community write-ups cover the rebalance command, node tags and the Telegram bot. That split has a practical consequence for an adopter: the command list is the public surface, while the behaviour behind some flags is documented in external articles and a private chat rather than in the repository, so treat those community guides as part of the documentation set. There is also a paid services command, a server command for running a server of paid services, and a gateway command that serves the ln-operator UI.

Saved node profiles and the LND directory override

Operators with more than one node, or with a node in a non default configuration, are handled by two mechanisms. The environment variable `BOS_DEFAULT_LND_PATH=/path/to/lnd/data/dir` overrides the directory bos searches, which is the quickest fix for a node that keeps its data somewhere unusual. For anything more structured, bos supports saved node profiles. You add a node with the nodes command and its add flag, or you create the profile directory by hand, drop a credentials.json into a folder named after the node inside ~/.bos/, and fill in three fields: the base64 tls.cert value, the base64 macaroon value, and the socket as host:port.

{
  "cert": "base64 tls.cert value",
  "macaroon": "base64 .macaroon value",
  "socket": "host:port"
}

The cert and macaroon content must be base64 encoded and newline stripped, which is where first attempts usually go wrong, since a raw copied file fails even though the values look right. The saved node list is itself viewable and adjustable through the nodes command.

What the project does not document

Two gaps stand out. The first is the supported LND version list, which runs from v0.21.0-beta to v0.21.4-beta and from v0.20.0-beta to v0.20.5-beta. Since the last push to the repository was on 2026-10-17, that gap is not a sign of an abandoned project, but it does mean an operator on a newer LND build is running an unsupported combination, and no statement exists about what breaks. The second gap is that the repository publishes no GitHub releases, so there is no tagged version history to page through, only the npm version and a CHANGELOG.md in the tree. A third, smaller gap is that the credential section is cut off mid sentence, so the exact command for turning files into base64 is not shown and you have to work that out yourself. There is also no documented rollback story: if a version upgrade breaks compatibility, nothing in the project says how to move back to the previous release.

Deployment choices: npm, Docker and the appliance route

For a home node the npm install is the simplest route, but the repository also ships a Dockerfile, and a Docker Hub pulls badge suggests the container image is the more common way to run it on a node appliance. The image is built on node:24-alpine, installs bash, sets the working directory to /app/, copies the repository in, runs npm ci and exposes the bos binary as the entrypoint, so the container is the CLI itself rather than a wrapper around a daemon. Install notes exist for Docker and BTCPayServer, for RaspiBlitz, for RaspiBolt on Debian, and for Umbrel, which tells you the intended audience is appliance operators rather than only desktop developers. Licence is MIT, which is the permissive end of the scale and means redistribution and modification carry little friction, with the usual requirement to keep the copyright notice intact. The dependency list is long, including ln-service, ln-accounting, ln-sync, ln-telegram and a paid services package, which explains why the tool covers so much more than balances without any of it being expanded on.

Editorial conclusion

Adopt bos if you already run LND and want balance, fee and rebalance answers without leaving the shell, and if you can point it at a node whose LND version falls in the range the project lists as supported. Skip it if you need a GUI, if you operate a backend other than LND, or if you need guarantees about future LND releases, because the supported version list stops at the v0.21.4-beta and v0.20.5-beta lines and the repository publishes no GitHub releases to track changes by tag. Before your first command, confirm two things: that your LND version is inside the supported range, and that the admin macaroon and tls.cert sit where bos expects them, since a wrong path shows up as a failed connection rather than a clear error message. Install with npm install -g balanceofsatoshis and run bos balance first, since it is the cheapest way to confirm credentials work before you touch a rebalance.

Frequently asked questions

Official sources

1. alexbosworth/balanceofsatoshis on GitHub
2. Issues
3. License: MIT
4. README