LIGHTNING-PLUGIN(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💖 plugin — managing your plugins with RPC, bestie ✨

okay so this is the LIGHTNING-PLUGIN(7) page and it is literally all about the plugin RPC command. buckle up 🎀

🌸 SYNOPSIS 🌸

plugin subcommand [plugin|directory] [options] ...

🦋 DESCRIPTION 🦋

The plugin RPC command is your remote control for dynamic plugins — meaning plugins that declared themselves 'dynamic' (in getmanifest). main character energy only 💅

subcommand (string) (one of "start", "stop", "rescan", "startdir", "list"): this is the vibe check — it decides what action gets taken:
- subcommand start takes a path to an executable as its argument and starts it as a plugin. the path may be an absolute path or a path relative to the plugins directory (default ~/.lightning/plugins). if the plugin is already running and the executable (checksum) has changed, the plugin is killed and restarted — except if it's an important (or builtin) plugin. if the plugin doesn't complete the 'getmanifest' and 'init' handshakes within 60 seconds, the command will timeout and kill the plugin 😭. additional options may be passed to the plugin, but that requires all parameters to be passed as keyword=value pairs using the -k|--keyword option — which is recommended. for example, this command starts the plugin helloworld.py (present in the plugin directory) with the option greeting set to 'A crazy':

$ lightning-cli -k plugin subcommand=start plugin=helloworld.py greeting='A crazy'

subcommand stop takes a plugin executable path or name as its argument and stops the plugin. if the plugin subscribed to 'shutdown', it may take up to 30 seconds before this command returns ⏳. if the plugin is important and dynamic, this will shutdown lightningd — yes, the whole daemon, no cap, be careful 💀.
subcommand startdir starts all executables it can find in directory (excl. subdirectories) as plugins. checksum and timeout behavior as in start applies.
subcommand rescan starts all plugins in the default plugins directory (default ~/.lightning/plugins) that are not already running. checksum and timeout behavior as in start applies.
subcommand list lists all running plugins (incl. non-dynamic).

plugin (string, optional): path or name of a plugin executable to start or stop.
directory (string, optional): path of a directory containing plugins.
options (array of strings, optional):
- (string, optional): keyword=value options passed to plugin, can be repeated.

✨ RETURN VALUE ✨

on success, an object is returned, containing:

command (string) (one of "start", "stop", "rescan", "startdir", "list"): the subcommand this is responding to 🫶

if command is "start", "startdir", "rescan" or "list":

plugins (array of objects):
- name (string): full pathname of the plugin.
- active (boolean): status; plugin completed init and is operational, plugins are configured asynchronously.
- dynamic (boolean): plugin can be stopped or started without restarting lightningd.

if command is "stop":

result (string): a message saying it successfully stopped.

🍓 ERRORS 🍓

on error, the reason why the action could not be taken upon the plugin is returned. it's giving honest feedback 🙈

👑 AUTHOR 👑

Antoine Poinsot darosior@protonmail.com is mainly responsible. stan him fr fr 💜

🌈 SEE ALSO 🌈

$ lightning-cli(1), lightning-listconfigs(7), writing plugins

⭐ RESOURCES ⭐

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

🔥 EXAMPLES 🔥

🧚 Example 1:

Request:

$ lightning-cli plugin -k "subcommand"="start" "plugin"="/root/lightning/tests/plugins/allow_even_msgs.py"

{
  "id": "example:plugin#1",
  "method": "plugin",
  "params": {
    "subcommand": "start",
    "plugin": "/root/lightning/tests/plugins/allow_even_msgs.py"
  }
}

Response:

{
  "command": "start",
  "plugins": [
    {
      "name": "/root/lightning/plugins/autoclean",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/chanbackup",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/bcli",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/commando",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/funder",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/topology",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/exposesecret",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/keysend",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/offers",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/pay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/recklessrpc",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/recover",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/txprepare",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-renepay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-xpay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/spenderp",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-askrene",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/sql",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-grpc",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-lsps-client",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-bip353",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/bookkeeper",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/tests/plugins/allow_even_msgs.py",
      "active": true,
      "dynamic": true
    }
  ]
}

🎀 Example 2:

Request:

$ lightning-cli plugin -k "subcommand"="stop" "plugin"="/root/lightning/tests/plugins/allow_even_msgs.py"

{
  "id": "example:plugin#2",
  "method": "plugin",
  "params": {
    "subcommand": "stop",
    "plugin": "/root/lightning/tests/plugins/allow_even_msgs.py"
  }
}

Response:

{
  "command": "stop",
  "result": "Successfully stopped allow_even_msgs.py."
}

💅 Example 3:

Request:

$ lightning-cli plugin "list"

{
  "id": "example:plugin#3",
  "method": "plugin",
  "params": [
    "list"
  ]
}

Response:

{
  "command": "list",
  "plugins": [
    {
      "name": "/root/lightning/plugins/autoclean",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/chanbackup",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/bcli",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/commando",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/funder",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/topology",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/exposesecret",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/keysend",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/offers",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/pay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/recklessrpc",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/recover",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/txprepare",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-renepay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-xpay",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/spenderp",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-askrene",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/sql",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/cln-grpc",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-lsps-client",
      "active": true,
      "dynamic": false
    },
    {
      "name": "/root/lightning/plugins/cln-bip353",
      "active": true,
      "dynamic": true
    },
    {
      "name": "/root/lightning/plugins/bookkeeper",
      "active": true,
      "dynamic": false
    }
  ]
}

and that's the whole page bestie!! 💖 this one's from Core Lightning v26.06.9, the LIGHTNING-PLUGIN(7) manual — go forth and start/stop your plugins responsibly, mwah 🫶✨🎀

📦 where this page comes from

nixpkgs unstable: clightning 26.06.9
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms