The offline guide

Your terminal.
Your invoice.

Inspect Lightning invoices on your own computer. Build once, then decode text and QR images without an API or internet connection.

Local decodingQR importJSON export

Run these commands in your local terminal.

Copy a command below, paste it into Terminal, and press Enter. This page is a guide; it does not execute commands on your computer. You need the project source and Rust with Cargo installed. The web decoder still uses the API.

01 · Setup

Prepare your terminal

Open your project folder. Replace this example path with the location of your checkout.

cd /path/to/lightening-tool
unset LIGHTNING_API_URL

unset removes a configured API URL from this terminal session. Omit --api-url to keep decoding local. These examples use macOS / Linux shell syntax.

02 · Build

Build once. Use offline.

Build the terminal application from the project root. The first build may need internet access to download Rust dependencies.

cargo build --release -p lightning-cli --bin bolt11-decoder

If all dependencies are already cached, you can build without network access:

cargo build --offline --release -p lightning-cli --bin bolt11-decoder

Cargo’s --offline controls dependency downloads. The built decoder runs locally by default; no Docker, backend, or Polar instance is needed.

03 · Interactive mode

Open the terminal UI

Launch Ratatui, paste a complete invoice, and press Enter. For a quick demo, press F2 to select a built-in sample.

./target/release/bolt11-decoder

Ratatui keyboard shortcuts
Key	Action
`Enter`	Decode the invoice or confirm a dialog
`F2`	Choose a built-in sample invoice
`F3`	Import a QR image using its local file path
`F4`	Cycle the expected network before decoding
`v`	Open or close the validation report after decoding
`Tab`	Switch between invoice details and JSON
`e`	Export JSON to a new file after decoding
`↑ / ↓`	Scroll through the result
`n / r`	Start another invoice after decoding
`Ctrl+U`	Clear the input or file path
`Esc`	Cancel a dialog; otherwise quit (returns from the validation report)
`Ctrl+C`	Quit from any screen

Use a terminal at least 72 × 24 characters; 100 × 32 is recommended. On a Mac, you may need to hold Fn while pressing a function key.

04 · Invoice text

Decode an invoice directly

Replace the placeholder with the complete BOLT11 string, keeping the quotes. From Polar’s invoice JSON, copy the payment_request value.

./target/release/bolt11-decoder decode 'PASTE_COMPLETE_INVOICE_HERE'

The command prints invoice details and the validation report as JSON. Invalid invoices produce a diagnostic report and a nonzero exit status.

05 · QR images

Read an image from disk

Try the included coffee QR. The sample is expired, so an expiry warning is expected.

./target/release/bolt11-decoder decode --image frontend/public/samples/coffee.png

Or replace the path below with your own image:

./target/release/bolt11-decoder decode --image '/absolute/path/to/my-invoice.png'

Use one QR code per PNG, JPEG, or WebP image, up to 10 MB and 4096 × 4096 pixels. The image is read locally.

06 · Validation

Check the expected network

For an invoice from Polar, expect regtest. A network mismatch adds a warning while keeping the invoice details available.

./target/release/bolt11-decoder --expected-network regtest decode 'PASTE_COMPLETE_INVOICE_HERE'

Accepted values: mainnet, testnet, signet, and regtest. Leave the option out to detect the network without an expectation.

07 · Export

Save the result as JSON

Redirect command output to a file in your current folder.

./target/release/bolt11-decoder decode --image frontend/public/samples/coffee.png > decoded-invoice.json

> replaces an existing file with the same name. For an export that refuses to overwrite files, press e on a Ratatui result.

08 · Reference

Explore command help

./target/release/bolt11-decoder --help
./target/release/bolt11-decoder decode --help

Try a fully offline demo

After building, disconnect from the internet and launch Ratatui. Use F2 for a sample or F3 for a saved QR. Signature and network checks still work. Expiry uses your computer’s clock; decoding cannot establish payment status, recipient identity, or route availability.

← Back to the decoder