LIGHTNING-COMMANDO(7)

🎀 LIGHTNING-COMMANDO(7) 🎀

okay bestie, welcome to lightning-commando(7) — yes the whole page has a manual name and everything, and honestly? she earned it. 💅

✨ NAME ✨

commando — literally the Command to Send a Command to a Remote Peer. a command inside a command, it's giving inception but make it lightning 🔥

✨ SYNOPSIS ✨

commando peer_id method [params] [rune] [filter]

✨ DESCRIPTION ✨

so the commando RPC command is a homage to bad 80s movies (no i'm not joking, that's canon 🌈). it sends a directly-connected peer_id a custom message containing a request to run method — with an optional dictionary of params. and here's the tea: generally the peer will only let you run a command if it has provided you with a rune which allows it. no rune, no vibes. 🫶

• peer_id (pubkey) — the peer you're commanding. yes, command them. main character energy 👑
• method (string) — the method to invoke on that peer
• params (one of, optional) — pick one of these:
  • (array) — an array of positional parameters
  • (object) — parameters for method.
• rune (string, optional) — the rune to authorize the command 🔑
• filter (object, optional) — filter to peer to apply to any successful result.

✨ RETURN VALUE ✨

on success, the return depends on the method you invoked. no cap, it's genuinely just "whatever that method gives you" — the commando wrapper isn't gatekeeping the results 💖

✨ ERRORS ✨

on failure, one of these error codes may be returned:

• -32600 — usually means peer is not connected 😭
• 19535 — the local commando plugin discovered an error
• 19536 — the remote commando plugin discovered an error
• 19537 — the remote commando plugin said we weren't authorized 🙈

also it can fail if the peer does not respond — in which case it will simply hang awaiting a response. like, just sit there. forever. staring. 💀 so maybe keep that in mind before you fire one off into the void.

✨ AUTHOR ✨

Rusty Russell rusty@rustcorp.com.au wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page. legend behavior, honestly 🫡

Christian Decker came up with the name "commando" — which almost excuses his previous adoption of the name "Eltoo". almost. 😭 (we love you christian)

✨ SEE ALSO ✨

lightning-commando-rune(7) — go read it, it's the rune lore ✨

✨ RESOURCES ✨

main web site: https://github.com/ElementsProject/lightning — go be nosy, it's fine 🌸

✨ EXAMPLES ✨

Example 1: 💫

request:

$ lightning-cli commando -k "peer_id"="nodeid020202020202020202020202020202020202020202020202020202020202" "rune"="zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA==" "method"="newaddr" "params"='{"addresstype": "p2tr"}'

{
  "id": "example:commando#1",
  "method": "commando",
  "params": {
    "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "rune": "zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA==",
    "method": "newaddr",
    "params": {
      "addresstype": "p2tr"
    }
  }
}

response:

{
  "p2tr": "bcrt1p338x07070707070707070707070707070707070707070707070707070707"
}

Example 2: 🦋

request:

$ lightning-cli commando -k "peer_id"="nodeid020202020202020202020202020202020202020202020202020202020202" "rune"="RXgu0DD_i0wSPEZkIDyZIWL0bSAGdhvJ_GHOQdTg04A9MSZpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZtZXRob2Q9bGlzdHBlZXJz" "method"="listpeers" "params"='["nodeid030303030303030303030303030303030303030303030303030303030303"]'

{
  "id": "example:commando#2",
  "method": "commando",
  "params": {
    "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "rune": "RXgu0DD_i0wSPEZkIDyZIWL0bSAGdhvJ_GHOQdTg04A9MSZpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZtZXRob2Q9bGlzdHBlZXJz",
    "method": "listpeers",
    "params": [
      "nodeid030303030303030303030303030303030303030303030303030303030303"
    ]
  }
}

response:

{
  "peers": [
    {
      "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "connected": true,
      "num_channels": 2,
      "netaddr": [
        "127.0.0.1:19736"
      ],
      "features": "0898882a8a59a1"
    }
  ]
}

Example 3: 💜

request:

$ lightning-cli commando -k "peer_id"="nodeid020202020202020202020202020202020202020202020202020202020202" "rune"="QUJEYMLGgiaJvMDv_MhR2hiMKIBTbq-PrL-KxcIlirQ9MiZtZXRob2Q9cGF5JnBuYW1lYW1vdW50bXNhdDwxMDAwMA==" "method"="pay" "params"='{"bolt11": "lnbcrt100n1pnt2bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000", "amount_msat": 9900}'

{
  "id": "example:commando#3",
  "method": "commando",
  "params": {
    "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "rune": "QUJEYMLGgiaJvMDv_MhR2hiMKIBTbq-PrL-KxcIlirQ9MiZtZXRob2Q9cGF5JnBuYW1lYW1vdW50bXNhdDwxMDAwMA==",
    "method": "pay",
    "params": {
      "bolt11": "lnbcrt100n1pnt2bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000",
      "amount_msat": 9900
    }
  }
}

response:

{
  "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
  "payment_hash": "paymenthashcmdpycp10cp10cp10cp10cp10cp10cp10cp10cp10cp10cp10cp10",
  "created_at": 1738000000,
  "parts": 1,
  "amount_msat": 9900,
  "amount_sent_msat": 9900,
  "payment_preimage": "paymentpreimagec010101010101010101010101010101010101010101010101",
  "status": "complete"
}

---

and that's the whole page bestie, you ate it up 🍓 this lil doc is from Core Lightning v26.06.9 — go forth and command your peers responsibly 💖✨🎀