vincenzopalazzo
/
rgb-cln
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
rgb-cln/doc/reckless.7.md

151 lines
4.9 KiB
Markdown
Raw Normal View History

Reckless: add man page
2022-11-02 18:48:24 +00:00
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:
doc: update reckless documentation
2024-02-02 17:12:13 +00:00
**reckless** **install**[@*commit/tag*] *plugin\_name*
Reckless: add man page
2022-11-02 18:48:24 +00:00
reckless will exit early in the event that:
doc: fix display of lists and code blocks in manpages. The conversion from markdown to manpages does not display lists and code blocks correctly if they are not preceded by an empty line. Changelog-None
2023-10-14 09:09:05 +01:00
Reckless: add man page
2022-11-02 18:48:24 +00:00
- the plugin is not found in any available source repositories
doc: update reckless documentation
2024-02-02 17:12:13 +00:00
- dependencies are not successfully installed
Reckless: add man page
2022-11-02 18:48:24 +00:00
- 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:
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **uninstall** *plugin\_name*
Reckless: add man page
2022-11-02 18:48:24 +00:00
disables the plugin, removes the directory.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **search** *plugin\_name*
Reckless: add man page
2022-11-02 18:48:24 +00:00
looks through all available sources for a plugin matching
this name.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **enable** *plugin\_name*
Reckless: add man page
2022-11-02 18:48:24 +00:00
dynamically enables the reckless-installed plugin and updates
the config to match.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **disable** *plugin\_name*
Reckless: add man page
2022-11-02 18:48:24 +00:00
dynamically disables the reckless-installed plugin and updates
the config to match.
**reckless** **source** **list**
list available plugin repositories.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **source** **add** *repo\_url*
Reckless: add man page
2022-11-02 18:48:24 +00:00
add another plugin repo for reckless to search.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**reckless** **source** **rm** *repo\_url*
Reckless: add man page
2022-11-02 18:48:24 +00:00
remove a plugin repo for reckless to search.
OPTIONS
-------
Available option flags:
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**-d**, **--reckless-dir** *reckless\_dir*
Reckless: add man page
2022-11-02 18:48:24 +00:00
specify an alternative data directory for reckless to use.
Useful if your .lightning is protected from execution.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**-l**, **--lightning** *lightning\_data\_dir*
Reckless: add man page
2022-11-02 18:48:24 +00:00
lightning data directory (defaults to $USER/.lightning)
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
**-c**, **--conf** *lightning\_config*
Reckless: add man page
2022-11-02 18:48:24 +00:00
pass the config used by lightningd
**-r**, **--regtest**
use the regtest network and config instead of bitcoin mainnet
**-v**, **--verbose**
request additional debug output
doc: update reckless documentation
2024-02-02 17:12:13 +00:00
**--network**=*network*
specify bitcoin, regtest, liquid, liquid-regtest, litecoin, signet,
or testnet networks. (default: bitcoin)
Reckless: add man page
2022-11-02 18:48:24 +00:00
NOTES
-----
doc: update reckless documentation
2024-02-02 17:12:13 +00:00
Reckless currently supports python and javascript plugins.
Reckless: add man page
2022-11-02 18:48:24 +00:00
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,
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 01:44:56 +00:00
the option flag **reckless -d=<my\_alternate\_dir>** may be used to
Reckless: add man page
2022-11-02 18:48:24 +00:00
relocate the reckless directory from its default. Consider creating a
permanent alias in this case.
doc: update reckless documentation
2024-02-02 17:12:13 +00:00
Python plugins are installed to their own virtual environments. The
environment is activated by a wrapper (named the same as the plugin)
which then imports and executes the actual plugin entrypoint.
Reckless: add man page
2022-11-02 18:48:24 +00:00
For Plugin Developers:
To make your plugin compatible with reckless install:
doc: fix display of lists and code blocks in manpages. The conversion from markdown to manpages does not display lists and code blocks correctly if they are not preceded by an empty line. Changelog-None
2023-10-14 09:09:05 +01:00
Reckless: add man page
2022-11-02 18:48:24 +00:00
- 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 <<alex@endothermic.dev>> 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: <https://github.com/lightningd/plugins>
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>