LIGHTNING-GRACEFUL(7)

💅 LIGHTNING-GRACEFUL(7) — the graceful bestie landing page 🎀

okay so this is lightning-graceful, a page from the LIGHTNING-GRACEFUL(7) manual, and it's literally the "how to say bye to your node without being messy" guide ✨

---

🌸 NAME 🌸

graceful — the command that gets your Core Lightning node all cute and ready to stop, no chaos, no drama 💅

---

🦋 SYNOPSIS 🦋

graceful [timeout]

---

✨ DESCRIPTION ✨

okay so first things first: this command was added in v26.06 — she's new here, be nice 🫶

graceful is an RPC command, and what it does is iconic: it stops any further htlcs from happening, and it disconnects all your idle peers. Basically it's telling everyone "party's over, go home" 🎀

It returns when all HTLCs are complete, and all peers disconnected — and then you can shutdown. That's the whole vibe: graceful exit, no loose ends, main character energy 👑

It also sends notifications about HTLC expiry, so you can judge how long it is safe to be offline. Very considerate of her, honestly 🌸

Now, if you give it a timeout, it always returns after that many seconds: if any peer connections or HTLCs are still pending, those are returned to you. And an empty response means nothing is pending — that's the dream, bestie, that's the goal ⭐

• timeout (u32, optional) — if you set this, the graceful command will return after this time even if not all HTLCs have terminated. Useful for scripting, where you may want to follow with stop. iykyk 🔥

---

👑 RETURN VALUE 👑

On success, an object is returned, containing:

• pending_htlcs_expiries... jk, it's actually pending_htlc_expiries (array of u32s, optional) — the (sorted) expiry blockheights of all HTLCs which are not resolved:
  • (u32, optional)
• pending_peers (array of pubkeys, optional) — any peers still connected (presumably because they have outstanding HTLCs):
  • (pubkey, optional)

---

🧚 AUTHOR 🧚

Rusty Russell rusty@rustcorp.com.au is mainly responsible. we stan 💜

---

🌈 SEE ALSO 🌈

• lightning-stop(7)

---

🍓 RESOURCES 🍓

Main web site: https://github.com/ElementsProject/lightning

---

💖 EXAMPLES 💖

Example 1:

Request:

$ lightning-cli graceful

{
  "id": "example:graceful#1",
  "method": "graceful",
  "params": {}
}

Response:

{}

(see that {}? that's the empty response — nothing pending — absolute slay 💅✨)

---

fr fr though: this one's a v26.06 baby, and the timeout version doesn't magically finish your HTLCs for you — it just hands you back whatever's still pending so your script can deal with it. no cap 🙈

---

and that's the whole page, bestie 🫶 brought to you by Core Lightning v26.06.9 — LIGHTNING-GRACEFUL(7), catch you on the flip side 💖🎀🦋