diff --git a/doc/Makefile b/doc/Makefile index 527b47bca..b6df0fbf9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -102,7 +102,8 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-listnodes.7 \ doc/lightning-listconfigs.7 \ doc/lightning-help.7 \ - doc/lightning-getlog.7 + doc/lightning-getlog.7 \ + doc/reckless.7 doc-all: $(MANPAGES) doc/index.rst diff --git a/doc/reckless.7.md b/doc/reckless.7.md new file mode 100644 index 000000000..ab74473dd --- /dev/null +++ b/doc/reckless.7.md @@ -0,0 +1,142 @@ +reckless - install and activate a CLN plugin by name +==================================================== + +SYNOPSIS +-------- + +**reckless** [*options*] **install/uninstall/enable/disable/source** *target* + +DESCRIPTION +----------- + +Reckless is a plugin manager for Core-Lightning. Typical plugin +installation involves: finding the source plugin, copying, +installing dependencies, testing, activating, and updating the +lightningd config file. Reckless does all of these by invoking: + +**reckless** **install** *plugin_name* + +reckless will exit early in the event that: +- the plugin is not found in any available source repositories +- dependencies are not sucessfully installed +- the plugin fails to execute + +Reckless-installed plugins reside in the 'reckless' subdirectory +of the user's `.lightning` folder. By default, plugins are activated +on the `bitcoin` network (and use lightningd's bitcoin network +config), but regtest may also be used. + +Other commands include: + +**reckless** **uninstall** *plugin_name* + disables the plugin, removes the directory. + +**reckless** **search** *plugin_name* + looks through all available sources for a plugin matching + this name. + +**reckless** **enable** *plugin_name* + dynamically enables the reckless-installed plugin and updates + the config to match. + +**reckless** **disable** *plugin_name* + dynamically disables the reckless-installed plugin and updates + the config to match. + +**reckless** **source** **list** + list available plugin repositories. + +**reckless** **source** **add** *repo_url* + add another plugin repo for reckless to search. + +**reckless** **source** **rm** *repo_url* + remove a plugin repo for reckless to search. + +OPTIONS +------- + +Available option flags: + +**-d**, **--reckless-dir** *reckless_dir* + specify an alternative data directory for reckless to use. + Useful if your .lightning is protected from execution. + +**-l**, **--lightning** *lightning_data_dir* + lightning data directory (defaults to $USER/.lightning) + +**-c**, **--conf** *lightning_config* + pass the config used by lightningd + +**-r**, **--regtest** + use the regtest network and config instead of bitcoin mainnet + +**-v**, **--verbose** + request additional debug output + +NOTES +----- + +Reckless currently supports python plugins only. Additional language +support will be provided in future releases. + +Running the first time will prompt the user that their lightningd's +bitcoin config will be appended (or created) to inherit the reckless +config file (this config is specific to bitcoin by default.) +Management of plugins will subsequently modify this file. + + +Troubleshooting tips: + +Plugins must be executable. For python plugins, the shebang is +invoked, so **python3** should be available in your environment. This +can be verified with **which Python3**. The default reckless directory +is $USER/.lightning/reckless and it should be possible for the +lightningd user to execute files located here. If this is a problem, +the option flag **reckless -d=** may be used to +relocate the reckless directory from its default. Consider creating a +permanent alias in this case. + +For Plugin Developers: + +To make your plugin compatible with reckless install: +- Choose a unique plugin name. +- The plugin entrypoint is inferred. Naming your plugin executable + the same as your plugin name will allow reckless to identify it + correctly (file extensions are okay.) +- For python plugins, a requirements.txt is the preferred medium for + python dependencies. A pyproject.toml will be used as a fallback, + but test installation via `pip install -e .` - Poetry looks for + additional files in the working directory, whereas with pip, any + references to these will require something like + `packages = [{ include = "*.py" }]` under the `[tool.poetry]` + section. +- Additional repository sources may be added with + `reckless source add https://my.repo.url/here` however, + https://github.com/lightningd/plugins is included by default. + Consider adding your plugin lightningd/plugins to make + installation simpler. +- If your plugin is located in a subdirectory of your repo with a + different name than your plugin, it will likely be overlooked. + +AUTHOR +------ + +Antoine Poinsot wrote the original reckless plugin on which this is +based. + +Rusty Russell wrote the outline for the reckless utility's function + +Alex Myers <> is mostly responsible for the +reckless code and this man page, with thanks to Christian Decker for +extensive review. + +SEE ALSO +-------- + +Core-Lightning plugins repo: + +RESOURCES +--------- + +Main web site: +