Mercurial > libervia-backend
changeset 3488:c80a0f864b5d
doc: updated doc following global renaming
line wrap: on
line diff
--- a/doc/configuration.rst Sun Mar 21 18:16:52 2021 +0100 +++ b/doc/configuration.rst Sun Mar 21 18:23:58 2021 +0100 @@ -4,7 +4,7 @@ Configuration ============= -Salut à Toi main configuration is set in a file named ``sat.conf`` (which may be prefixed +Libervia main configuration is set in a file named ``libervia.conf`` (which may be prefixed by a ``.`` if you want to hide it on suitable platforms). It is a common file used both by backend and all frontends (and even related project like SàT Pubsub). @@ -12,18 +12,18 @@ - ``/etc`` - ``~`` (``$HOME`` or your home directory) - XDG directory for configuration (most of time it is - ``~/.config/sat/``) + ``~/.config/libervia/``) - the parent directory of SàT installation path If several configurations files are found, they are merged. In case of conflict, the option parsed last is the one used (in other words: if you have an option set in -``/etc/sat.conf`` and the same one set in ``~/.sat.conf``, the one from ``~/.sat.conf`` +``/etc/libervia.conf`` and the same one set in ``~/.libervia.conf``, the one from ``~/.libervia.conf`` will be used because it is parsed after ``/etc``). Format ====== -``sat.conf`` is using the `INI`_ file format as understood by Python's `SafeConfigParser`_ +``libervia.conf`` is using the `INI`_ file format as understood by Python's `SafeConfigParser`_ (meaning that you can use interpolation). The ``DEFAULT`` section is used for global options, this is where you specify where are @@ -35,17 +35,17 @@ have the name of a web site used with Libervia web framework. -To recapitulate, you can have the following sections in your ``sat.conf``: +To recapitulate, you can have the following sections in your ``libervia.conf``: ``[DEFAULT]`` the main, global section frontend name (in lower case) frontend specific settings. Some examples: - - ``[cagou]`` - - ``[jp]`` - - ``[primitivus]`` - - ``[libervia]`` + - ``[desktop]`` + - ``[cli]`` + - ``[tui]`` + - ``[web]`` ``[plugin <plugin name>]`` backend plugin specific settings. Some examples: @@ -116,7 +116,7 @@ ; default room to use in the "Join room" menu default_muc = sat@chat.jabberfr.org - [primitivus] + [tui] log_level = debug ; how the logs are formatted ; note that "%" must be doubled here @@ -124,15 +124,15 @@ ; use bracketed paste mode bracketed_paste = true - [jp] - ; how to use xdotool to refresh Firefox when doing "jp blog edit" + [cli] + ; how to use xdotool to refresh Firefox when doing "li blog edit" blog_preview_open_cmd = firefox -new-tab {url} blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" ; and below the equivalent with Konqueror # blog_preview_open_cmd = konqueror {url} # blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" - [libervia] + [web] ; do we want "http", "https" or "both"? connection_type = both port = 8080
--- a/doc/index.rst Sun Mar 21 18:16:52 2021 +0100 +++ b/doc/index.rst Sun Mar 21 18:23:58 2021 +0100 @@ -26,8 +26,8 @@ installation.rst overview.rst configuration.rst - /jp/index.rst - /primitivus/index.rst + /libervia-cli/index.rst + /libervia-tui/index.rst /contribuing/index.rst
--- a/doc/jp/account.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,75 +0,0 @@ -================================ -account: XMPP account management -================================ - -``account`` command help you to create or manage the XMPP account of a server, using -In-Band Registration (`XEP-0077`_). - -.. _XEP-0077: https://xmpp.org/extensions/xep-0077.html - -create -====== - -Create a XMPP account. You have to specify your jid and password as positional arguments. -By default the registration is done on ``localhost`` with default XMPP Client 2 Server -port (i.e. 5222), but you can specify other host/port using ``-H HOST, --host HOST`` and -``-P PORT, --port PORT``. You may also specify an e-mail address using ``-e EMAIL, --email -EMAIL`` (use of this data depend of the server implementation). - -By default, no SàT profile is created and associated to this new XMPP account, but you can -use ``-p PROFILE, --profile PROFILE`` if you are willing to have one. - -example -------- - -Create account for the new user Nestor at ``nestor@example.org`` and associate it with the -SàT profile ``nestor``:: - - $ jp account create nestor@example.org some_password -p nestor - - -modify -====== - -Modify an existing XMPP account password. This will modify the XMPP account linked to the -given profile. - -.. note:: - - Only the XMPP password on the server is changed, not the one registered in the - parameter of SàT. You may have to update the parameter of your profile if the new - password doesn't correspond to your parameters one (you can do that with jp param set - or with most SàT frontends in parameters). - -example -------- - -Change the XMPP password of the XMPP account of the default profile:: - - $ jp account modify new_password - - -delete -====== - -Delete the XMPP account linked to the given profile from the XMPP server. Before using -this command, please be sure to understand well that **THIS WILL REMOVE THE WHOLE XMPP -ACCOUNT AND DATA FROM THE XMPP SERVER**. - -By default a confirmation is requested, you can do this without confirmation by using -``-f, --force``, however this is **NOT RECOMMENDED**, be sure to understand what you're -doing if you use this option (and be sure to spell correctly the profile, if you forget -the ``-p PROFILE, --profile`` argument for instance, this would delete entirely the -default profile). - -.. note:: - - Be extra careful with this command, as it will remove the whole account from the - server, and the associated data. - -example -------- - -Delete the XMPP account of Pierre, which is not on the local server anymore:: - - $ jp account delete -p pierre
--- a/doc/jp/ad-hoc.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,120 +0,0 @@ -======================= -ad-hoc: Ad-Hoc commands -======================= - -Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used -either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get -list of connected users, send a service announcement, restart parts of the server), or -execute about anything (e.g. control a physical robot with XMPP). - -run -=== - -Run an ad-hoc command. You may specify the node to run as positional argument, or let it -empty to list available commands. - -By default the commands from your server are used, but with ``-j JID, --jid JID`` you can -specify a different entity. - -You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and -``-S, --submit`` as many time as needed. ``--field`` expect a ``KEY`` which is the name -of the field to set. If you don't know which name to use, you can run the command to -automatise a first time manually with ``--verbose, -v`` flag, this will display fields -names when you have to fill them. - -Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then -if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and -so on as many times as you need. - -Don't forget that you can use your shell substitution capabilities if necessary, for -instance if you have a pre-registered announce to send. - -examples --------- - -Get a list of available commands on your server to launch a command:: - - $ jp ad-hoc run - -If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements -to online users. This can be useful to notify an imminent maintenance of the server. Here -we notify online users that the server will be shutdown in 30 min, using a shell -substitution capabilities with a pre-registered message in the file -``~/announces/maintenance_30.txt``, then we submit it:: - - $ jp ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S - -Get your server uptime (if supported by your server):: - - $ jp ad-hoc run uptime - -Run the commands available at the service with the jid ``someservice.example.org``:: - - $ jp ad-hoc run -s someservice.example.org - -Run you server commands with verbosity so you get the name of the fields that you can fill -automatically later:: - - $ jp ad-hoc run -v - -.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html - -list -==== - -List ad-hoc commands available at a service. - -examples --------- - -List ad-hoc commands available at your server:: - - $ jp ad-hoc list - -List ad-hoc commands available at a chat service:: - - $ jp ad-hoc list -j conference.example.org - -remote -====== - -Create a remote control from launched media players. Ad-hoc commands to control the media -player will be added to your device, allowing anybody allowed (including yourself from an -other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc. - -To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can -specify who is allowed to control this media player with the following options: - -``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]`` - jids of entities allowed to control the media player - -``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]`` - groups (from your roster) allowed to control you remote - -``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]`` - groups (from your roster) which are **NOT** allowed to control your media player - -``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]`` - jids of entities which are **NOT** allowed to control your media player - -If you want the commands to run repeatedly (in opposition of stopping after first action -is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it. - -.. note:: - - SàT already creates automatically a remote control if it finds a media player. This - manual way to create a remote control predate the automatic remote control, and is - currently more flexible in that you can specify who can access the remote control - (automatic remote control is only accessible by the jid of the profile). - -examples --------- - -Create a remote control for a running VLC instance:: - - $ jp ad-hoc remote vlc -l - -Create a remote control for a running SMPlayer instance, and allowing anybody from your -``housemates`` group to use it:: - - $ jp ad-hoc remote smplayer -g housemates -l
--- a/doc/jp/avatar.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,47 +0,0 @@ -=============================== -avatar: retrieve/upload avatars -=============================== - -Avatars are images associated to an XMPP entity. Several XMPP extensions are in use, SàT -tries to hide the technical details so avatar are as easy as possible to manipulate for -end-user. - -get -=== - -Retrieve the avatar of the given entity. Entity jid is specified as positional argument. - -If an avatar is found, a path to its cached file is printed. Please note that this is the -cache used by all SàT ecosystem, **do not modify the cached image**. You may use it for -read-only access, or copy it if you want to modify the image. - -You may use the ``-s, --show`` argument to display the found avatar. The software used to -display the image can be specified in SàT configuration (cf. :ref:`configuration`), in the -``[jp]`` section: the ``image_cmd`` setting let you specify the path to the software. If -``image_cmd`` is not used, ``jp`` will try some common software, and if none is found, it -will try to open the image in a browser (which may sometimes result in using the default -image software of the platform). - -When available, cached avatar is returned by defaut. If you want to ignore the cache, use -the ``--no-cache`` option (of course this can result in more network requests). - -example -------- - -Get the avatar of ``louise@example.org`` and display it:: - - $ jp avatar get --show louise@example.org - - -set -=== - -Upload and set the given avatar for the profile. The only required argument is the path to -the image to use as avatar. - -example -------- - -Set the avatar of the default profile:: - - $ jp avatar set ~/photos/some_photo.jpg
--- a/doc/jp/blog.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,299 +0,0 @@ -.. highlight:: sh - -================================ -blog: (micro)blogging management -================================ - -Blog commands are high level tools to handle an XMPP blog. -They are using the generic pubsub arguments - -set -=== - -publish a blog item. - -:ref:`pubsub_common` commands are used to specify the destination item. - -``stdin`` is used to get the body of the blog post. - -examples --------- - -Create a blog post with a body, a subject, 2 tags, and with comments allowed:: - - $ echo "This is post body" | jp blog set -T "This is a test message" -t test -t jp -C - -Create a blog post with rich content using `markdown` syntax, and no subject:: - - $ echo "This is a **rich** body" | jp blog set -S markdown - -get -=== - -get command retrieves one or more blog post(s) from specified location (by default the -personal blog of the profile). - -output can be customised to only retrieve some keys, or to use a specific template. For -instance, the following command retrieves only the title and publication date of the -personal blog of the profile:: - - $ jp blog get -k title -k published - -:ref:`pubsub_common` commands are used to specify the blog location. - -examples --------- - -Retrieve personal blog of the profile using `fancy` output with a verbosity of 1 (to show -publication date):: - - $ jp blog get -O fancy -v - -Retrieve *title* and *publication date* of last 3 blog posts from the blog at -https://www.goffi.org:: - - $ jp blog get -m 3 -u https://www.goffi.org -k title -k published - -Retrieve last 2 posts of personal blog, and output them in browser using default -template:: - - $ jp blog get -m 2 -O template --oo browser - -.. _jp-blog_edit: - -edit -==== - -With edit command you can create a new blog post or modify an existing one using your -local editor (the one set in ``$EDITOR``). You'll edit 2 things: the body of the post, and -the metadata which contain things like title, comments infos, or tags. - -For some common editors (like **vim** or **Emacs**), the editor will be automatially -opened using a split screen with *body* in one side, and metadata on the other. If the -editor is not supported or doesn't support split screen, you'll edit first the *body*, then -the *metadata*. You can also specify editor and arguments in ``sat.conf``, see -`configuration <edit_conf_>`_ below - -If you don't change anything or publish an empty blog post, the edition will be cancelled. - -In the metadata (see `below <edit_metadata_>`_ for details), you can use ``"publish": -false`` to forbid the publication (or set it with ``--no-publish argument``). In this -case, when you'll save your modification and quit your editor, the blog post will not be -published but saved locally in a draft. To continue your work later, just start your -edition with the ``-D, --current`` option like this:: - - $ jp blog edit -D - -Note that item location must be re-specified if it has been used to create the draft, so -you'll have to reproduce the arguments to specify service, node or item (or the URL), -other data like tags will be restored from draft file of metadata. - -You can specify the syntax by using ``-S SYNTAX, --syntax SYNTAX``. If not specified, the -syntax set in your parameters will be used. - -When you edit a blog post, it is often useful to activate the ``-P, --preview`` option, -this will launch a web browser and refresh the page each time you save a modification in -your editor. By default, the browser registered as default in your system will be used, -and a new tab will be opened on each modification. This is not ideal, and we recommand to -set you configuration to activate automatic refreshing of the page instead, see `preview -configuration <edit_preview_>`_ below to see how to do. - -.. note:: - - If --preview doesn't work, use ``jp blog preview`` (see below) to get error messages. - On GNU/Linux, Be sure that inotify Python module is installed correctly. - -examples --------- - -Edit a new blog post with comments on your personal blog, using default syntax and preview:: - - $ jp blog edit -P --comments - -Modifiy a draft previously saved using the ``"publish": false`` metadata:: - - $ jp blog edit -D - -Correct a typo in your last published blog post:: - - $ jp blog edit --last-item - -Edit the blog item at an HTTPS URL using XHTML syntax:: - - $ jp blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml - -Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that -https://example.net is a XMPP blog node):: - - $ jp blog edit -u https://www.example.net - -.. _edit_metadata: - -metadata --------- - -Metadata is set using a JSON object. The key you can use are: - -publish - boolean indicating if item can be published. Set to ``false`` if you want to work on a - draft and to avoid accidental publication. - -atom_id - atom entry identifier. This should not be modified manually. - -published - time of initial publication (unix time). This should not be modified manually. - -language - language of the content - -comments - array of URIs to the comments node, if any. - -tag - array of tags, if any - -author - human readable name of the entry author - -author_jid - jid of the author. This should notbe modified manually. - -author_jid_verified - true if the pubsub service confirmed that author_jid is the one of the publisher. It is - useless to modify this variable. - -title - the title of the message - -title_rich - the rich title of the message, in current text syntax. It will be automatically - converted to xhtml. - -.. _edit_conf: - -configuration -------------- - -editor -^^^^^^ - -Local editor used is by default the one set in ``$EDITOR`` environment variable, but you -can specify one in ``sat.conf``. To do so, you have to set the name of an editor -executable in the ``editor`` option in ``[jp]`` section. - -You can specify the args to use by using ``blog_editor_args`` option. Use -``{content_file}`` to get the path of the main content file (the body of the blog post), -and ``{metadata_file}`` to get the path of the json metadata. - -.. sourcecode:: cfg - - [jp] - editor = kate - blog_editor_args = {content_file} {metadata_file} - -.. _edit_preview: - -preview -^^^^^^^ - -To set the preview, you can use the options ``blog_preview_open_cmd`` and -``blog_preview_update_cmd`` in your ``[jp]`` section. the former is the command to use to -open your browser when edition starts, and the later is the command to use when a -modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file. - -This can be used to activate automatic refreshing of the page. - -For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is -installed on your system, and enter the following lines in your ``sat.conf``: - -.. sourcecode:: cfg - - [jp] - blog_preview_open_cmd = konqueror {url} - blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" - -For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the -following lines in your ``sat.conf``: - -.. sourcecode:: cfg - - [jp] - blog_preview_open_cmd = firefox -new-tab {url} - blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" - -This *xdotool* technique can be adapted to other browsers. - -syntax extensions -^^^^^^^^^^^^^^^^^^ - -A dictionary with a mapping from syntax name to file extension can be used. This can be -useful to activate the right syntax highlighting in your editor. There is a default -mapping which can be overriden. - -The mapping is set in the ``syntax_ext_dict`` option of the ``[jp]`` section of your -``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files -instead of the default ``.md``, you can use this: - -.. sourcecode:: cfg - - [jp] - syntax_ext_dict = {"markdown": "markdown"} - -the first ``markdown`` is the name of the syntax (could be an other syntax like ``xhtml``), -while the second if the file extension. - -preview -======= - -This command will show the specified file in browser, and refresh it when changes are -detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be -used if you have already started an edition with ``jp blog edit`` but forgot to use the ``-P, --preview`` arguments. - -example: --------- - -Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``:: - - $ jp blog preview ~/local/sat/blog/some_name/blog_something.md - -.. _jp-blog_import: - -import -====== - -With this command you can import an external blog in a XMPP blog at the specified pubsub -location. - -The import is done using an *importer* name and a *location* which depends of the importer -(it can be a path to a file, an URL to a blog, or something else). Let empty to get list -of importers, and specify only importer name to get its description. - -By default, found images are re-uploaded to XMPP server, if you want to keep original -URLs, use the ``--no-images-upload`` option. - -Alternatively, you can re-upload images except for a specific host with ``--upload-ignore-host UPLOAD_IGNORE_HOST``. The images for the specified host will keep there original URLs while other will be uploaded to XMPP server. - -You shoud specify original blog host using ``--host HOST`` argument, this is used notably -to reconstruct relative URLs of media. - -Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. - -examples: ---------- - -List available importers:: - - $ jp blog import - -Get description of ``dotclear`` importer:: - - $ jp blog import dotclear - -Import a Dotclear blog:: - - $ jp blog import dotclear /path/to/dotclear.dump - -Import a Dotclear blog without uploading images:: - - $ jp blog import --no-images-upload dotclear /path/to/dotclear.dump
--- a/doc/jp/bookmarks.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,98 +0,0 @@ -============================ -bookmarks: get/set bookmarks -============================ - -Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons, -XMPP has several ways to handle bookmarks, and SàT handle them as transparently as -possible. - -With SàT there are 3 places where you can get/store your bookmarks: - -local - the bookmarks is stored only locally in the database of SàT. It won't be available to - other devices. -private - the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to - use this if PubSub storage is available -pubsub - the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to - store bookmarks. - -When possible, you can specify ``auto`` to let SàT choose the best location (i.e. -``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible). - -.. _XEP-0049: https://xmpp.org/extensions/xep-0049.html -.. _XEP-0223: https://xmpp.org/extensions/xep-0223.html - - -list -==== - -Get and print available bookmarks. You specify the location of the bookmarks to print -using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default -all bookmarks from all locations are printed. - -Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or -URLs. - -After printing the bookmarks location, the bookmarks will show the name and location (jid -for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if -autojoin is set. - - -examples --------- - -Retrieve all MUC bookmarks:: - - $ jp bookmarks list - -Retrieve all bookmarked URL stored in PubSub:: - - $ jp bookmarks list -l pubsub -t url - - -remove -====== - -Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as -positional argument. If you are deleting an URL, you need to specify it with ``-t url`` - -By default a confirmation is requested, use ``-f, --force`` if you don't want it (with -usual caution). - -examples --------- - -Delete the bookmark of a MUC room that you are not following anymore:: - - $ jp bookmarks remove some_old_room@conference.example.net - -Delete the bookmark of a URL without requesting confirmation:: - - $ jp bookmarks remove -t url https://unused_url.example.net - - -add -=== - -Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as -positional argument. If you are bookmarking an URL, you need to specify it with ``-t -url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it. - -For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``, -and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically -when you're connecting. - -If you're using add on a jid/URL which already exists, the metadata will be updated. - -examples --------- - -Add a bookmark to Salut à Toi official chat room:: - - $ jp bookmarks add sat@chat.jabberfr.org -a - -Add a link to Salut à Toi official website:: - - $ jp bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel"
--- a/doc/jp/common_arguments.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,214 +0,0 @@ -================ -common arguments -================ - -Some arguments are used in many commands. This page describe them. - -.. _jp-common_profile: - -profile -======= - -profile arguments are really common, they allow you to select your profile. -If you don't select any, the default profile is used, which is the first -profile created or the one you have explicitly set. You can check which profile -is used by default with ``jp profile default``. - -The common arguments for profile are: - -``-p PROFILE, --profile PROFILE`` - to select the name of your profile. It can be a profile key like ``@DEFAULT@`` - -``-c, --connect`` - connect the profile to the XMPP server before doing anything else. If your - profile is already connected, nothing happen. This is specially useful in scripts. - -``--start-session`` - starts a session without connecting, this can be needed if you can't connect but - you need to access your session e.g. to change parameters. - This is advanced used and is not need in most common cases. - -``--pwd PASSWORD`` - the password of your profile, needed if the session is not started yet. - -.. note:: - - using the ``--pwd`` option is not secure if you are not the only user of your machine: - the password will appear **IN CLEAR** in the list of launched processes, or in the - history of your shell. If the profile password is needed and not specified, it will be - prompted (with echo disabled). If you are on a shared machine or if anybody can access - your shell history at some point, you should either connect first your profile with an - other frontend (Primitivus for instance), or avoid the ``--pwd`` option and use the - prompt instead. - -.. _pubsub_common: - -pubsub -====== - -pubsub arguments are used in many commands, they allow you to select a service, node and -items. Depending on the command, you may only not be able to select an item, or you may -select one or multiple items. - -The common arguments for pubsub are: - -``-u PUBSUB_URL, --pubsub-url PUBSUB_URL`` - retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an - ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to - retrieve the location of the XMPP node/item, if available. - Note that you can override parts of the location in the URL if you specify service, node - or item. - - e.g.:: - - $ jp blog get -u https://www.goffi.org - -``-s SERVICE, --service`` - used to specifiy the JID of the pubsub service - -``-n NODE, --node NODE`` - used to specifiy the pubsub node - -``-i ITEM, --item ITEM`` - for commands where an item can be specified, you do it with this option. In some - commands, multiple items can be specified, in this case just use this arguments several - times. - -``-L, --last-item`` - when an item id is needed, you can use this option to retrieve the last published item. - e.g.:: - - $ jp blog edit --last-item - -``-M, --max-items`` - use to specify a maxium number of items to retrieve, when it makes sense. - Note that this is using the pubsub max (i.e. defined in - `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should - implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in - this case the ``-m, --max`` argument should be prefered. See below for RSM common - arguments. - -result set management -===================== - -Result Set Management (RSM) common arguments are used to navigate into pages of results -when lot of elements may be expected. Given a result with a large number of arguments, a -*page* is set of elements which correspond to an *index* (a page number). For instance if -you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to -20 included. - - -``-a ITEM_ID, --after ITEM_ID`` - find page after this item. You usually use the last item id of the latest page you got. - -``-b ITEM_ID, --before ITEM_ID`` - find page before this item. This this usually used when you check items backwards - -``--index RSM_INDEX`` - index of the page to retrieve. Note that first page has index **0**. - -``-m RSM_MAX, --max RSM_MAX`` - used to specify a maxium number of items to retrieve per page. Note that the actual - maximum number of items per page used may be lower if the service used consider that - your request is too big. - -message archive management -========================== - -Message Archive Management (MAM) argument is used by some commands (related to instant message or -pubsub) to filter results. - -There is currently only one argument in this group: - -``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` - specify a MAM filter to use. Depending on the service supporting MAM, some filters can - be used to do things like full text search. The available filters depend on the service - you use, please check documentation of your service. - -order-by -======== - -Order-By argument specify how the returned elements are sorted. - -There is currently only one argument in this group: - -``-o {creation,modification}, --order-by {creation,modification}`` - specify how result is sorted. with ``creation``, first created element is returned - first. There is no notion of *creation* of *modification* in original - `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an - existing id will overwrite the older one, creating a new item. With this option, we use - the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and - *creation* time is the time when the first item has been published, before being - overwritten. - - In the case of ``modification``, if an item is overwritten, it reappears on top, this is - the default pubsub sorting order. - -progress -======== - -This single option may be used when a long operation is happening, like a file transfer. - -``-P, --progress`` - Show progress bar. - -verbose -======= - -``--verbose, -v`` - Add a verbosity level (can be used multiple times). Use to have more concise output by - default when it makes sense. - -.. _draft_common: - -draft -===== - -Common arguments used when an edition is potentially long to do, and a file may be kept -until publication. - - -``-D, --current`` - Used when you have started to edit something (e.g. a blog post), which is not yet - published, and you want to continue your work. - - e.g.:: - - $ jp blog edit -D - -``-F DRAFT_PATH, --draft-path DRAFT_PATH`` - Used when you have started to edit something and want to continue your work from this - file. In other words, it's similar to ``-D, --current`` except that you specify the file - to use instead of using the last available draft. - -.. _jp-output: - -output -====== - -Output is used when you want to get the result of the command in a specific way. It may be -used, for instance, to retrieve the result formatted in JSON so the data can be easily -manipulated by a script, or if you want only a specific element of the result. - -``-O {…}, --output {…}`` - specifiy the output to use. Available options depends of the command you are using, - check ``jp [your command] --help`` to know them. - - e.g.:: - - $ jp blog get -O json - -``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` - depending of the output selected, you may have options to customise the output. - For instance, if you use the ``template`` output, you may use an option to display the - result in a browser. - - e.g.:: - - $ jp blog - - Some options expect parameters, in this case they can be specified using ``=``. - - e.g. specifiying a template to use:: - - $ jp blog get -O template --oo browser --oo template=/tmp/my_template.html
--- a/doc/jp/debug.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,93 +0,0 @@ -===================================================== -debug: tools to help debugging/monitoring Salut à Toi -===================================================== - -``debug`` groups commands to monitor or manipulate SàT and XMPP stream. - -.. _jp-debug_bridge_method: - -bridge method -============= - -Call a method of the bridge. You have to provide the name of the method and the arguments -as positional arguments. Arguments are evaluated as Python code (using ``eval``), so you -need to properly escape them (for your shell **and** Python). You can either split your -Python arguments as many shell arguments, or put them in a single shell argument. - -You profile is automatically set if the method requires it (using the value of ``-p -PROFILE, --profile PROFILE``), so you must not specify it as an extra argument. - -You can refer to `Bridge API documentation`_ to get core methods signatures - -.. _Bridge API documentation: https://wiki.goffi.org/wiki/Bridge_API - - -examples --------- - -Send a message using a single shell arguments for all Python arguments. We -use first the method name (``messageSend``), then the required arguments (see `Bridge -API documentation`_ for details), without the profile as it is automatically set. We -specify them as Python in one shell argument, so we use single quote (``\```)first for -s hell string, and inside it we use double quote (``"``) for Python strings:: - - $ jp debug bridge method messageSend '"louise@example.org", {"": "test message"}, {}, "auto", {}' - -.. note:: - - This is for debugging only, if you want to send message with jp, use :ref:`jp-message_send`. - -Get version string of SàT:: - - $ jp debug bridge method getVersion - - -bridge signal -============= - -Send a fake signal. This is specially useful to test behaviour of a frontend when a -specific event happens. To use is you just need to specify the name of the signal and the -arguments to use (using Python eval in the same way as for jp-debug_bridge_method_). - -example -------- - -Send a note with ``info`` level and hand written XMLUI. Here me use a shell variable to -store the level, so we can easily change it if we want to use an other level for tests. -Note the use of quotes (to escape both for shell and Python):: - - $ LEVEL='info'; jp debug bridge signal -c actionNew '{"xmlui": '"'"'<?xml version="1.0" ?><sat_xmlui title="test title" type="dialog"><dialog level="'$LEVEL'" type="note"><message>test message\non\nseveral\nlines</message></dialog></sat_xmlui>'"'"'}' '""' -1 - - -monitor -======= - -Show raw XML stream. By default, output is pretty formatted/highlighted and you get all -streams in both direction. You can filter the direction using ``-d {in,out,both}, ---direction {in,out,both}``. - -For this to work, you need to set the option ``Activate XML log`` in the ``Debug`` section -of your parameters. - -Verbosity is used, to print details on the direction of a stanza, use ``--verbose, -v`` - -example -------- - -Monitor raw XML stream:: - - $ jp debug monitor -v - -theme -===== - -Show the colour constants in their respective colour, according to background (``light`` -or ``dark``). If backround option is not set in ``sat.conf``, it will be autodetected, and -colour theme will be modified accordingly. - -example -------- - -Show colours with the set background:: - - $ jp debug theme
--- a/doc/jp/encryption.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,126 +0,0 @@ -======================================== -encryption: encryption sessions handling -======================================== - -Salut à Toi being an XMPP client does encryption by default between client and server. In -addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the -payload of messages are encrypted to be hidden from the servers (and their -administrators). The ``encryption`` commands are here to handle those e2e encryption -sessions and algorithms. - -.. note:: - - For the moment, only one 2 one chat messages can be e2e encrypted - -algorithms -========== - -Display e2e encryption algorithms available in this instance of Salut à Toi. - -example -------- - -Show available e2e algorithms:: - - $ jp encryption algorithms - -get -=== - -Display which encryption session is currently active with the given entity. - -The only required argument is the JID of the entity. - -If not e2e encryption session exist, a message will be displayed and jp will exit with a -non zero code: this means that the messages are in clear in the XMPP servers, but normal -XMPP encryption is not affected (message should still be encrypted between client and -server and between servers). - -If an e2e encryption session exist, you'll see the algorithm name and its namespace. In -case of e2e encryption which only works from device to device (e.g. it's the case with -``OTR`` which doesn't support multiple devices), you'll also see the resources of the -devices where the encryption is active in ``directed_devices`` - -example -------- - -Check if session is encrypted with Louise:: - - $ jp encryption get louise@example.org - -start -===== - -Start e2e session with an entity. - -You need to specify the JID of the entity you want to start a session with as a positional -argument. - -By default, SàT will select itself the algorithm to use among those available, but you can -specify one using either its name with ``-n NAME, --name NAME`` or its namespace using -``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo`` -while the namespace is the longer (e.g. ``urn:xmpp:otr:0``). - -If an encryption session is started but one with an other algorithm was already there, the -original session will be stopped and replaced by one with the new requested algorithm. You -can change this behaviour by using ``--encrypt-noreplace``: in this case the command will -fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e -encryption session was already started with an other algorithm), and return a non-zero -code. If an e2e encryption session was already started with the requested algorithm, the -command will succeed in all cases and nothing will be changed. - -examples --------- - -Start e2e encryption with Pierre, using the algorithm selected by SàT:: - - $ jp encryption start louise@example.net - -Start an OMEMO session with Louise:: - - $ jp encryption start -n omemo louise@example.org - -stop -==== - -Terminate an e2e session with given entity. The entity must be specified as positional -argument. - -After this command is run, the messages with specified entity will not be e2e encrypted -anymore (but this won't affect encryption between SàT and XMPP server and between XMPP -servers). - -example -------- - -Stop the e2e encryption session with Pierre:: - - $ jp encryption stop pierre@example.net - -trust ui -======== - -Run the user interface to handle trust with given entity and given algorithm. The user -interface depends on the algorithm used, but it generally shows you the fingerprints -associated with your contact or contact devices, and asks you if you trust them or not. - -The only mandatory argument is the jid of your contact. - -By default the currently active encryption session algorithm is used, but you may manage -trust for another algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE, ---namespace NAMESPACE``. - -.. note:: - - Trusting a contact or a device means that you certify that this contact or device is - the one you want to talk too. You should not trust a device if you have not verified by - an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the - fingerprint physically if possible (i.e. in front of your contact, not with computer - networks in the middle). - -example -------- - -Manage ``OMEMO`` trust with Louise devices:: - - $ jp encryption trust ui -n omemo louise@example.org
--- a/doc/jp/event.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ -======================== -event: events management -======================== - -Event commands allows you to create/modify or get data about an event, and to manage your -invitees. - -list -==== - -List events available on a service - -example -------- - -Retrieve events of profile:: - - $ jp event list - -.. _jp-event_get: - -get -=== - -Get metadata about a specific event. - -example -------- - -Retrieve an event metadata:: - - $ jp event get -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0' - -.. _jp-event_create: - -create -====== - -Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``, -and an id with ``-i ID, --id ID`` (default id is used if omitted). - -Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key -can be a custom data or one of: - -name - name of the event -description - details of the event -image - URL of the main picture of the event -background-image - URL of image to use as background -register - a boolean value, set to ``true`` if you want to register the event in your local list - -example -------- - -Create an event about to celebrate New Year:: - - $ jp event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg - - -modify -====== - -This command in the same way as jp-event_create_ but modify an existing event. You need to -specify the node of the event to modify using ``-n NODE, --node NODE``. - -example -------- - -Add a background image to the New Year event created above:: - - $ jp event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg - - -invitee -======= - -Subcommands to handle guests. Please check :ref:`jp-event_invitee`.
--- a/doc/jp/event_invitee.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ -.. _jp-event_invitee: - -======================================== -event/invitee: event invitees management -======================================== - -``invitee`` groups commands to invite somebody to an event, get or set data about an invitee, and list all invitees. You can send an invitation by e-mail to people without XMPP account. - -.. _jp-event_invitee_get: - -get -=== - -Retrieve the RSVP status of one guest. Note that you must the invitees node and not the -event node. To retrieve invitees node, use :ref:`jp-event_get` with the event node. - -You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare -jid will be used). - -If no response is known yet, no data is returned. - -example -------- - -Get RSVP of Louise:: - - $ jp event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org - - -.. _jp-event_invitee_set: - -set -=== - -Set your own RSVP data. Note that as for jp-event_invitee_get_ you must use -invitees node and not the event node. - -Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of -``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value -must be an integer. - -example -------- - -Indicate that you'll come to an event with 3 guests:: - - $ jp event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3 - -list -==== - -Get and format the RSVP of your invitees. Note that as for jp-event_invitee_get_ and -jp-event_invitee_set_ you must use invitees node and not the event node. - -By default, only people who have answered are shown. You may use ``-m, --missing`` to show -other people which were invited, but have not answered yet. When using this option, you -can also use ``-R, --no-rsvp`` to only show people which have not answered yet. - -You'll also have a small summary indicating how many people who can expect at your event. - -example -------- - -Get the full list of invitees (including those who didn't answered yet) with the RSVP formatted:: - - $ jp event invitee list -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -m - -invite ------- - -Invite somebody to an event. The invitation is done by e-mail, a guest account will be -created. Contrary to other ``invitee`` commands, in this one you'll use the event node -directly. - -This command is really similar to :ref:`jp-invitation_create` - -E-mail address is specified using ``-e EMAIL, --email EMAIL`` and you'll need to give an -URL template (using ``-U URL_TEMPLATE, --url-template URL_TEMPLATE``)leading to your -website page handling the invitation (for Libervia default invitation page is -``<your_server>/g/<uuid>``). You can use ``{uuid}`` as a placeholder which will be -replaced by event's id. - -You'll probably want to specify the name of the invitee, using ``-N NAME, --name NAME`` -and your own name (as the host inviting), using ``-H HOST_NAME, --host-name HOST_NAME``. -The language spoken by your guest can be specified using ``-l LANG, --lang LANG``, it is -mainly useful if you have many invitee speaking different languages. - -example -------- - -Pierre is inviting Louise (whose e-mail address is ``louise_email@example.net``) to an -event he's organising:: - - $ jp event invitee invite -e louise_email@example.et -N "Louise" -H "Pierre" -l fr -U "https://www.example.org/g/{uuid}" -u "xmpp:pierre@example.org?;node=generic%2F61400ea7-a2a2-4ce0-9b68-3735b602f671"
--- a/doc/jp/file.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,173 +0,0 @@ -======================================== -file: files sending/receiving/management -======================================== - -``file`` group all commands related to file management, and allows you to send easily a -file to a contact or device from the command line. - -send -==== - -Send a file to a contact. - -The file will be sent using best available method (which is Jingle File Transfer when -available), and will try to send the file in P2P when possible. If P2P is possible, the -signal is sent through the server (metadata, negotiation, etc.), while the file itself -goes directly from the source device to the target device. When P2P is not possible, the -file may go through the server or an other one (if a proxy is used for instance). - -When sending a file, you specify one or more file(s) to send, and the either the bare jid -or the full jid of the target device. If bare jid is specified, the main resource will be -used. - -You'll usually want to see the progression of the transfer, use ``-P, --progress`` for -that. - -If you send several files at once, you may want to use ``-b, --bz2`` to group them in a -single compressed ``tar.bz2`` archive (the client receiving the files will then receive a -single file, than the user can then decompress). - -By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to -specify another one. - -The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace -NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like -a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group -of files, for instance for a photo album). - -examples --------- - -Send a file to Louise, with a progress bar:: - - $ jp file send -P some_file.ext louise@example.org - -Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in -the ``/some/path`` path:: - - $ jp file send -P -N holidays -d /some/path some_photo.jpg files.example.org - -.. _jp-file_request: - -request -======= - -Ask to get a file from a device/sharing service. A file is requested using one or more -metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H -HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo -HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N -NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific -and not (yet?) XMPP standards. - -If you already know the hash, it's the most efficient and recommended way to retrieve a -file. - -You need to specify the full jid of the device or the sharing service as a positional -argument. - -By default the file is downloaded in current directory, but you can specify an other one -(and an other filename) with ``-D DEST, --dest DEST``. - -If you want to see progression of the transfer, use ``-P, --progress``. - -examples --------- - -Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service -``files.example.org``, with a progress bar:: - - $ jp file request -P -d photos/demo_album -n some_file.jpg files.example.org - -Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't -specify it), and save it to file ``dest_file.txt``:: - - $ jp file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org - -receive -======= - -Wait for a file (or several ones) to be received, and accept it if it match criteria. - -You should specify which jid you are expecting a file from, using the positional -arguments. If you don't, all files will be accepted, which can be dangerous if some -malicious user send you a file at this moment. - -To see progression (this is recommended), you can use the ``-P, --progress`` options. - -By default, if a file with the same name as the proposed one exists, the transfer will be -denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely -trust the sender in this case, as the name is chosen by her, and could be malicious, or it -could override an important file. - -If you expect several files, you can use the ``-m, --multiple``, in this case the command -won't stop after the file received file, and you'll have to manually stop it with -``Ctrl-C`` or by sending a ``SIGTERM``. - -File(s) will be written in the current directory, but you may specify an other destination -with ``--path DIR``. - -examples --------- - -Accept and receive the next file, save it to local directory and show a progress bar:: - - $ jp file receive --progress - -Several files are expected from Louise, accept them and store them do -``~/Downloads/Louise``:: - - $ jp file receive --multiple --path ~/Downloads/Louise louise@example.org - -get -=== - -Download a file from an URI. This commands handle URI scheme common with XMPP, so in -addition to ``http`` and ``https``, you can use it with ``aesgcm`` scheme (encrypted files -with key in URL, this is notably used with OMEMO encryption). - -As usual, you can use ``-P, --progress`` to see a progress bar. - -example -------- - -Download an encrypted file with a progress bar, and save it to current working directory -with the same name as in the URL (``some_image.jpg``). The URL fragment part (after ``#``) -is used for decryption, so be sure to not leak the URL when you manipulate one:: - - $ jp file get -P "aesgcm://upload.example.org/wvgSUlURU_UPspAv/some_image.jpg#7d8509c43479591f8d8492f84369875ca983db58f43225c40229eb06d05b2037c841b2346c9642a88ba4a91aa96a0e8f" - -upload -====== - -Upload a file to your XMPP server (or an other entity if specified). The upload will be -done using `XEP-0363 (HTTP File Upload)`_, and the public URL to retrieve the file will be -printed. Note that anybody knowing this URL can download the file you've uploaded. - -The path to the file to upload is expected as first argument, then optionally the entity -of the service to upload too (by default, this is autodetected if your server offers this -feature). - -As usual, you can use ``-P, --progress`` to see a progress bar. - -You can encrypt the file using ``AES GCM`` with the ``-e, --encrypt`` argument. You will -then get an ``aesgcm://`` link instead of the usual ``https``, this link contains the -decryption key (in the fragment part) so be sure to not leak it and to transmit it only -over encrypted communication channels. - -.. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload - -example -------- - -Upload a document to a server:: - - $ jp file upload -P ~/Documents/something_interesting.odt - -Encrypt and upload a document to server:: - - $ jp file upload -P -e ~/Documents/something_secret.odt - -share -===== - -Subcommands for advanced file sharing. Please check :ref:`jp-file_share`.
--- a/doc/jp/file_share.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,108 +0,0 @@ -.. _jp-file_share: - -================================== -file/share: advanced files sharing -================================== - -``share`` groups commands for listing file available on a device/service, sharing a file -or directory, and inviting people to retrieve files. - -.. _jp-file_share_list: - -list -==== - -List files available on a device or sharing service. You mainly have to specify the jid of -the device/service where the files are stored (if jid is omitted, your own jid will be -used, so you can check what you are sharing). - -.. note:: - - you have to use the full jid of the device if you want to list files available on a - device. - -You may specify a path using ``-d PATH, --path PATH``. - -File and directories are printed with a different colour if you use default output. - -examples --------- - -List files shared from a device (note that we use a full jid here):: - - $ jp file share list louise@example.org/some_resource - -List files available on a sharing service at the path ``/photos``:: - - $ jp file share list -d photos files.example.org - -Louise wants to list the file shared by Pierre:: - - $ jp file share list pierre@files.example.org - -path -==== - -Share a local file or directory with a list of entities, or publicly. The files can then -be listed or requested using jp-file_share_list_ or :ref:`jp-file_request`. - -You specify the file or directory the positional ``path`` argument. By default the name of -the file/directory is used, but you can give a different one using ``-n NAME, --name -NAME``. - -You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many -time as necessary. If you don't specify any entity, the file will only be accessible by -your own devices. If you want to make your file accessible to everybody, use ``--public`` -(note that this means that your file is accessible to the world, i.e. also to people you -don't know, so use this option carefully). - -examples --------- - -Share the file ``interesting_doc.odt`` with Pierre and Louise:: - - $ jp file share path -j pierre@example.net -j louise@example.org interesting_doc.odt - -Imagine that you have built a weather station and want to make its data public. You can -share the directory ``~/weather_station_data`` with the world, using the name ``public -weather data``:: - - $ jp file share path --public --name "public weather data" ~/weather_station_data - -invite -====== - -This command send an invitation for a file sharing repository to an XMPP entity. - -The invitation is a non standard (yet?) way to notify somebody of the existence of a files -repository. - -Beside the positional arguments ``service`` and ``jid``, which are respectively the -service where is the files repository and the jid of the entity to invite, you mainly have -to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and -``N NAMESPACE, --namespace NAMESPACE``. - -Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a -generic files repository or a photo album. - -Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL, ---thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of -the album in e.g. Libervia. - -example -------- - -Pierre wants to invite Louise to view his ``summer holidays`` photo album:: - - $ jp file share invite -P "photos/summer holidays" -t photos pierre@files.example.net - louise@example.org - -affiliations -============ - -subcommands for file sharing affiliations management. please check :ref:`jp-file_share_affiliations`. - -configuration -============= - -subcommands for retrieving/modifying file sharing node configuration. please check :ref:`jp-file_share_configuration`.
--- a/doc/jp/file_share_affiliations.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,56 +0,0 @@ -.. _jp-file_share_affiliations: - -============================================================= -file/share/affiliations: file sharing affiliations management -============================================================= - -``affiliations`` let you manage access permission to your shared files repository, in a -way similar as for pubsub. - -Affiliations with file sharing are not standard and will only work with the SàT file -sharing component. - -Affiliations are similar to pubsub ones: - -``owner`` - Has full permissions on the node, including changing affiliations. Owner can't be - changed at the moment. - -``publisher`` - Can read, upload and delete files - -``member`` - Can access file but can't modify them or add new ones - -``none`` - Is not a member of this node, use it to remove an existing affiliation. - - -get -=== - -Retrieve entities affiliated to this file sharing node, and their role - -example -------- - -Get affiliations of a file sharing node:: - - $ jp file share affiliations get -P "/some/path" louise@files.example.org - -set -=== - -Set affiliations of an entity to a file sharing node. - -examples --------- - -Allow read access to a photo album to Louise:: - - $ jp file share affiliations set -c files.example.net -P "/albums/holidays" -a louise@tazar2.int member - -Remove access to a directory from an old address of Pierre, and give it to the new one:: - - $ jp file share affiliations set -c files.example.net -N "some_namespace" -P - "/interesting/directory" -a pierre@example.com none -a pierre@example.org member
--- a/doc/jp/file_share_configuration.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -.. _jp-file_share_configuration: - -========================================================= -file/share/configuration: file sharing node configuration -========================================================= - -``configuration`` commands are use to check or modify settings of a file sharing node. -This is not standard and specific to SàT file sharing component. - -The configuration is similar as pubsub one. - -Only ``access_model`` can be used so far, with the ``open`` or ``whitelist`` values. - - -get -=== - -Retrieve file sharing node configuration. - -example -------- - -Get configuration of a file sharing node:: - - $ jp file share configuration get -P "/some/path" louise@files.example.org - -set -=== - -Set configuration of a file sharing node. - -example -------- - -Make a repository public:: - - $ jp file share configuration set -c files.example.net -P "/public_files" -f - access_model open
--- a/doc/jp/forums.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,102 +0,0 @@ -============================== -forums: forums topics handling -============================== - -Forums are internally a way to organise blog nodes open to many publishers. The ``forums`` -commands let you manage the structure of topics. You may have several different structures -in one PubSub forums node, this can be useful if you have multi-lingual forums. - -.. _jp-forums_get: - -get -=== - -Get and print the structure of forums. Beside the classic PubSub node arguments, you may -specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have -several structures of forums, for instance one per language. - -If you use the default output, the verbosity is used to retrieve details of topics. - -examples --------- - -Get structure of default forum with details:: - - $ jp forums get -v - -Get structure of French forums in JSON:: - - $ jp forums get -k fr -O json - - -edit -==== - -Edit the structure of XMPP forums. As for jp-forums_get_ you may specify the key beside -the classic PubSub node arguments. The edition works the same as for :ref:`jp-blog_edit`. - -To edit the structure you'll get a JSON file which is a list of object where the topic -metadata are set. You can use the following metadata: - -``main-language`` - a language code, using `ISO 639`_ -``name`` - short name of the forum -``title`` - title of the topic/category in the given language -``short-desc`` - small description of the topic/category -``desc`` - long description of the topic/category -``uri`` - URI to the PubSub node containing the messages of the topic (it's actually a blog node - with suitable permissions). URI must only be set for topic, not for categories. -``sub-forums`` - list of object with the same metadata (i.e. other topics or categories) - -Here is a small example of a forum structure: - -.. sourcecode:: json - - [ - { - "main-language": "en", - "name": "short-name", - "title": "This is a category", - "short-desc": "short description about the category", - "desc": "this is a an example of a long description" - "sub-forums": [ - { - "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", - "title": "some intereting topic", - "short-desc": "This is a description explaining what the topic is about" - }, - { - "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", - "title": "a second topic", - "short-desc": "This topic is about bla bla bla" - }, - ], - }, - { - "main-language": "en", - "title": "An other category", - "sub-forums": [ - { - "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", - "title": "yet another topic", - "short-desc": "This is a demo topic, made for an example" - }, - ] - } - ] - - -.. _ISO 639: https://www.iso.org/iso-639-language-codes.html - -example -------- - -Edit structure of forums on a PubSub service:: - - $ jp forums edit -s pubsub.example.org
--- a/doc/jp/identity.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ -============================= -identity: identity management -============================= - -Identity use several XMPP extensions (like vcards) to retrieve or set informations about -an entity. For now it's really basic and only nickname and avatar are managed. - -get -=== - -Retrieve informations about the identity behind an XMPP entity. You only have to specify -the jid of the entity, and you'll get (if set) his/her/its nickname and data about the -avatar. - -When available, cached values are returned by defaut. If you want to ignore the cache, use -the ``--no-cache`` option (of course this can result in more network requests). - -example --------- - -Get identity information about an entity:: - - $ jp identity get somebody@example.org - -set -=== - -Set identity data to the server, using various XMPP extensions. So far, you can only -change the nickname of an entity using ``-n, --nick`` or or more times - -example -------- - -Set 2 nicknames for default profile:: - - $ jp identity set -n toto -n titi
--- a/doc/jp/index.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,89 +0,0 @@ -.. _jp-documentation: - -== -jp -== - -``jp`` is the CLI (Command Line Interface) frontend of Salut à Toi - -Overview -======== - -``jp`` is a powerful tool to work with Salut à Toi/XMPP. -With it you can send chat messages, share files, retrieve avatars, write blog entries, etc. - -Usage -===== - -To get help on commands or their options, use:: - - $ jp --help - -which can be used on any command, so if you need help on ``message send`` command, just do:: - - $ jp message send --help - -With jp, you always enter commands first, then options and arguments. - -There are several levels of commands: first one is the main category (``message``, -``blog``, ``avatar``, etc.), then there are often subcommands (e.g. ``message send``). - -After the commands come the options. For instance if you want to send a message, you can -get the available options with ``--help`` as explained above:: - - $ jp message send --help - usage: jp message send [-h] [-p PROFILE] [--pwd PASSWORD] [-c] [-l LANG] [-s] - [-n] [-S SUBJECT] [-L SUBJECT_LANG] - [-t {chat,error,groupchat,headline,normal,auto}] - [-e ALGORITHM] [--encrypt-noreplace] [-x | -r] - jid - - positional arguments: - jid the destination jid - - optional arguments: - -h, --help show this help message and exit - -p PROFILE, --profile PROFILE - Use PROFILE profile key (default: @DEFAULT@) - --pwd PASSWORD Password used to connect profile, if necessary - -c, --connect Connect the profile before doing anything else - -l LANG, --lang LANG language of the message - -s, --separate separate xmpp messages: send one message per line - instead of one message alone. - -n, --new-line add a new line at the beginning of the input (usefull - for ascii art ;)) - -S SUBJECT, --subject SUBJECT - subject of the message - -L SUBJECT_LANG, --subject_lang SUBJECT_LANG - language of subject - -t {chat,error,groupchat,headline,normal,auto}, --type {chat,error,groupchat,headline,normal,auto} - type of the message - -e ALGORITHM, --encrypt ALGORITHM - encrypt message using given algorithm - --encrypt-noreplace don't replace encryption algorithm if an other one is - already used - -x, --xhtml XHTML body - -If you want to send a message to, say, ``pierre@example.net``, and encrypt it with OMEMO, -just do the following:: - - echo "hi, I'm writing with jp" | jp message send -e omemo pierre@example.net - -(note that with OMEMO, you need to have previously validated fingerprint of your contact -for this to work). - -The different commands are explained in dedicated sections. - -.. toctree:: - :caption: jp commands: - :glob: - :maxdepth: 2 - - common_arguments - * - - -Tutorial -======== - -You can check this third party tutorial: https://blog.agayon.be/sat_jp.html
--- a/doc/jp/info.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,77 +0,0 @@ - -================================== -info: retrieve various information -================================== - -``info`` groups subcommands used to retrieve read-only informations. - -disco -===== - -Display discovery information (see `XEP-0030`_ for details). This can be used to check -which features you server or a service is offering, and which items are available (items -can be services like chat room, gateways, etc). - -You only have to specify the jid of the entity to check, and optionally a node. - -By default both infos and items are requested, but you can restrict what to request by -using ``-t {infos,items,both}, --type {infos,items,both}`` - -.. _XEP-0030: https://xmpp.org/extensions/xep-0030.html - - -example -------- - -Request infos and items from a server:: - - $ jp info disco example.org - -version -======= - -Request software version of an entity. You only need to specify the jid of the entity as -positional argument. - -Depending of the software and its configuration, you have software version, software name, -and the operating system on which the software is running. - -example -------- - -Check version of a server:: - - $ jp info version example.org - -session -------- - -Give information about the session of the given profile. You'll get the full jid currently -used on the server, and the time when the session was started (which may not be the same -time as when the connection with the XMPP server was started). - -example -------- - -Get session informations:: - - $ jp info session - -devices -------- - -List known devices for an entity. You'll get resource name, and data such as presence -data, and identities (i.e. name and type of the client used). - -If entity's bare jid is not specified, a list of your own devices is returned. - -example -------- - -List known devices of Louise:: - - $ jp info devices louise@example.org - -Check if we have other devices connected:: - - $ jp info devices
--- a/doc/jp/input.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,119 +0,0 @@ -================================================ -input: automatise commands using external inputs -================================================ - -``input`` is a way to use external data (like file in a specific format) as input -arguments. It may be seen as a something similar to ``--output`` but for inputs. - - -csv -=== - -CSV (for Comma-Separated Values) is a common format for tabular data. It is widely used in -spreadsheet software (at least at en export format). With ``csv`` command, you can use -columns a CSV file as arguments to jp commands. - -To set the command, you'll write in sequence what to do with each column of your data. -For each column you can: - -- specify a short option name using ``-s ARGUMENTS, --short ARGUMENTS`` (short options are - the ones with a single ``-``) -- specify a long option name using ``-l ARGUMENTS, --long ARGUMENTS`` (long options are - the ones with two ``-``) -- specify a positional argument using ``-p ARGUMENTS, --positional ARGUMENTS`` -- indicate to use the column data with ``stdin`` using ``-i, --stdin`` -- ignore the column if it's not used in the jp command, using ``-x, --ignore`` - -After each column specification, you may use a filter to manage the value. So far the -following filters are available: - -``-S, --split`` - This will split the value (on any whitespace character, discarding empty values) and - repeat the option which each item. This is useful when you are using an option which can - be repeated (like ``-t TAG, --tag TAG`` with ``jp blog set``). - -``-E ARGUMENTS, --empty ARGUMENTS`` - Indicate what to do if the column value is empty (by default en empty string is used). - You can use either ``skip`` to skip the whole row, or ``ignore`` so the option will not - be set at all (which is different from the default which will still set the option but - with an empty string). - -CSV file is read from stdin, and by default unicode is expected. You may force an encoding -by using ``--encoding ENCODING``. - -By default all the rows are read, but you may want to ignore first rows (if they are used -for columns title, or if you have already handled part of the list). To do that, use the -``-r ROW, --row ROW`` option. - -When you test your command, it is better to do a dry run to see what will happen. The -``-D, --debug`` option is here for that: if you set it, the commands won't be actually -run, but the exact command which would be executed will be printed on screen. You should -always use this option first until you're sure that what you want will be executed. - -You may add verbosity level to help debugging. With a verbosity level of 2 (i.e. ``-vv``) -the value read from CSV will be printed. - -By default stdout and stderr of each launched command is ignored, but you can log them to -files using respectively ``--log LOG`` and ``--log-err LOG_ERR`` where ``LOG`` and -``LOG_ERR`` are paths to a log file to create. - -Once all the sequence and options are set, you write the jp command that you want to use, -with all the needed static option (i.e. options which must be used each time). - - -example -------- - -Louise as a spreadsheet with a table like this: - -============================ ============ ============= =============== -title body internal data tags -============================ ============ ============= =============== -Some title a body ABC jp demo -Something else another body XYZ jp demo -Third one third body VWZ special_tag jp -This one doesn't have a body 123 jp demo numbers -last one last body 456 jp demo numbers -============================ ============ ============= =============== - -She wants to use it as input data to create blog posts. - -She first saves the file using CSV format, let's say to ``~/blog_input.csv``. - -Then she checks ``jp blog set --help`` to get name of options to use. She'll need to use -``--title`` for title, ``stdin`` for the body and ``-t`` for tags. Louise wants to -activate comments, so she also wants to use ``-C`` for all posts, and a tag to says it's -coming from the spreadsheet (using ``-t spreadsheet``) . - -The first row of the table is used for columns headers, so she'll start at row 1 with ``-r -1``. - -There is one row without body, Louise want to skip any row without body so she'll use the -``-E skip`` filter, just after specifying the body row. - -Reading column by column, the sequence is like this: - -``-l title`` - a title which goes to the ``--title`` long option of ``jp blog`` -``-i -E skip`` - a body which goes to the stdin of ``jp blog``. If the body is empty, the ``-E skip`` - filter tells to skip the whole row. -``-x`` - the ``internal data`` column is not used, so it is ignored -``-s t -S`` - the last column are the tags, so the ``-t`` short option is used. There are several of - them separated by spaces, so the ``-S`` filter is used to split the values. - -First she'll use the ``-D, --debug`` to check that the commands which will be executed are -the expected one:: - - $ jp input csv -D -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv - -Everything seems fine, so she'll actually launch the command by running the same command -line but without the ``-D`` option:: - - $ jp input csv -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv - -She could also have used ``--log`` and ``--log-err`` to check the logs of each command:: - - $ jp input csv -r 1 -l title -i -E skip -x -s t -S --log /tmp/jp_blog_stdout.log --log-err /tmp/jp_blog_stderr.log blog set -C -t spreadsheet < ~/blog_input.csv
--- a/doc/jp/invitation.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,109 +0,0 @@ -============================================== -invitation: invite people without XMPP account -============================================== - -Invitations allows you to invite people without XMPP account, so they can participate e.g. -to a discussion by using a specially generated link. This is a Salut à Toi specific -feature and those commands are rather low lever. - -.. _jp-invitation_create: - -create -====== - -Invite somebody to participate. This will create a guest account and a link with an -identifier to access this account, and send an invitation to the given email. - -The email is specified using ``-e EMAIL, --email EMAIL``, which can be used multiple times -to send the invitation to more than one address. - -You'll usually want to specify the name of the person you're inviting, using ``-n NAME, ---name NAME``, it may later be used in email sent or in the web page where your guest will -land. - -``-N HOST_NAME, --host-name HOST_NAME`` is used to specify the name of yourself (i.e. the -person which is inviting), it may be used in invitation message. - -You'll most of time have to specify the URL template using ``-u URL, --url URL``. This -will be used in the invitation email to construct the URL where your invitee will click. -You may use the string ``{{uuid}}`` in this template which will be replaced by the id -associated to the invitation. With Libervia, default invitation page is -``<your_server>/g/<uuid>``. - -The language of your guest can be specified using ``-l LANG, --lang LANG``, this is -notably useful if you have multilingual blog posts (e.g. for an event where people -speaking different languages are invited). - -The ``-x KEY VALUE, --extra KEY VALUE`` is used for extra data which depend on what you -are inviting your guests for. - - -example -------- - -Invite Louise, which is speaking French, to an event. The invitation is sent to her email -address ``louise_email@example.net``, is sent by Piotr, and must link to the Libervia -instance at ``https://www.example.org/g/<id>``. We use here the ``event_uri`` extra key:: - - $ jp invitation create -n Louise -N Pierre -e louise_email@example.net -l fr -u "https://www.example.org/g/{uuid}" -x event_uri xmpp:pierre@example.org?;node=MnXe4ic2X8RUz6JAJuw4f9;item=org.salut-a-toi.event%3A0 - - -get -=== - -Get metadata for one specific invitation. You only have to specify the invitation id, and -you may use the option ``-j, --with-jid`` to also get the jid used for the invitation -(this will start the session of the invitee). - -example -------- - -Get invitation data for invitation with id ``okFec4gDz75My7iQAVTmsc``:: - - $ jp invitation get okFec4gDz75My7iQAVTmsc -j - - -modify -====== - -This work the same way as jp-invitation_create_, you only have to specify the ``id`` of the -invitation. - -If you use the ``--replace`` argument, all the invitation data will be replaced by the -ones you're specifying. - -example -------- - -Change the language of the invitee for the invitation ``okFec4gDz75My7iQAVTmsc`` for -Slovak:: - - $ jp invitation modify -l sk okFec4gDz75My7iQAVTmsc - - -delete -====== - -Delete XMPP account created for an invitation and invitation data - -example -------- - -Delete invitation with id ``okFec4gDz75My7iQAVTmsc``:: - - $ jp invitation delete okFec4gDz75My7iQAVTmsc - - -list -==== - -List registered invitations. You may filter by the profile who made the invitation using -``-p PROFILE, --profile PROFILE``. -The invitations are shown by default using id as main data, and metadata below. - -example -------- - -List invitations:: - - $ jp invitation list
--- a/doc/jp/merge-request.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ -=============================================== -merge-request: create and manage merge requests -=============================================== - -Merge-request are used to propose some modifications to a project. They are generic and -are made to be used with several backends, but only Mercurial is implemented so far. - -To prepare a merge request with Mercurial, you just need to have a clone of the project, -and do your modifications (either directly, or in a bookmark, a branch, or a MQ patch). - -set -=== - -Create and publish a merge request. Once the modification on the project are done, simply -run the command from the repository (or specify its path with ``-r PATH, --repository -PATH``). If the project has set metadata (it can be done with a magic string in README), -you don't have to specify any service or node, it will be set automatically (but you still -can specify them if needed). - -You may associate one or more labels to your request using ``-l LABELS, --label LABELS``. - -By default, a confirmation is requested before publishing the request, you can publish -without confirmation by using the ``-f, --force`` flag. - -If you have already done a merge request and you just want to update it, check its id and -specify it with ``-i ITEM, --item ITEM``, this will override the previous request with the -new updated one. - -examples --------- - -Publish a merge request (to be executed from the repository of the project you have -modified):: - - $ jp merge-request set - -Update an existing merge request, which has the id ``123`` (to be executed from the -reposiroty of the project you have modified):: - - $ jp merge-request set -i 123 - -Do a merge request for repository at path ``~/some_project``, specifying a label -indicating it's work in progress (WIP):: - - $ jp merge-request set -r ~/some_project --label WIP - - -get -=== - -Get and print one or more merge requests. By default only some metadata are shown (without -the patches), but you can use ``--verbose, -v`` to show details. - -examples --------- - -Show some metadata of last 5 merge requests:: - - $ jp merge-request get -M 5 - -Display details for merge request with id 456:: - - $ jp merge-request get -v -i 456 - - -import -====== - -Import a merge request into your project. You mainly have to be in the project repository -(or specify it using ``-r PATH, --repository PATH``) and to specify the id of the patch to -import (using ``-i ITEM, --item ITEM``). The behaviour depends of the type of the patch, -for Mercurial, the patch will be imported as `MQ`_ patch. - -.. _MQ: https://www.mercurial-scm.org/wiki/MqExtension - -example -------- - -Import the merge request with id 321:: - - $ jp merge-request import -i 321
--- a/doc/jp/message.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ -.. highlight:: sh - -================================ -message: chat message management -================================ - -Message commands let you send chat messages or manage your server message archives. - -.. _jp-message_send: - -send -==== - -Send a message to a contact or a chat room. -``stdin`` is used as message source. -You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed. -You can manage your encrypted session using ``encryption`` command. - -examples --------- - -Send a message to a contact:: - - $ echo 'Salut à Toi!' | jp message send louise@example.net - -Send a message encrypted with OMEMO:: - - $ echo 'pssst, this message is encrypted' | jp message send -e omemo louise@example.net - -.. note:: - - Fingerprints of your destinee must have been accepted before using OMEMO, else message can't be encrypted - -Send a ``normal`` message marked as French with a subject:: - - $ echo 'Bonjour, je vous écris avec « Salut à Toi »' | jp message send -l fr -t normal -S 'Ceci est un message de test' - -mam -=== - -Query archives using MAM. -This command allows you to check message archive kept on the server (i.e. not the local copy). -You usually want to specify a starting point, and a number of message to retrieve. If too many messages -are available, you'll have to use RSM commands to navigate through the results. - -examples --------- - -Retrieve messages from last 2 days:: - - $ jp message mam -S "2 days ago" - -Retrieve messages from last 5 hours on SàT official chat room:: - - $ jp message mam -S "5 hours ago" -s sat@chat.jabberfr.org - -Retrieve 2 first messages of 2019 on SàT official chat room:: - - $ jp message mam -S 2019-01-01 -s sat@chat.jabberfr.org -m 2
--- a/doc/jp/param.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,124 +0,0 @@ -============================ -param: manage SàT parameters -============================ - -``param`` commands allows to retrieve or set parameters as well as to export/import them -to a XML file. - -Parameters are retrieve using a ``category`` and a ``name``, they are both case sensitive. - -``category`` is the name of the tabs that you see when you set parameters in a frontend -like Cagou or Libervia. - -.. note:: - - You need to have your session started to retrieve of modify parameters. If you can't - or are not willing to connect for any reason (e.g. no internet connection), you can - use the ``--start-session`` option to start the profile session without connecting it - to the XMPP server. - -get -=== - -Retrieve list of categories, parameters or a specific parameter value: - -- without argument, you'll get the list of categories -- with only a category specified, you'll get a list of parameters and their values -- with a category and a name, you'll get the value or requested attribute of the specified - parameters - -By default you'll get the value of the parameters, but you can request an other attribute -(for instance its ``type`` or ``constraint``) using the ``-a ATTRIBUTE, --attribute -ATTRIBUTE`` argument. - -You can set a security limit to retrieve only parameters allowed with this limit. -Security limit is an integer used in some frontends (like Libervia), to restrict -parameters modifiable by non privileged users. You can set it using ``--security-limit -SECURITY_LIMIT``, by default it is disabled (i.e. all parameters are returned). - -examples --------- - -Get list of categories:: - - $ jp param get - -Get list of parameters in ``General`` category:: - - $ jp param get General - -Get JID set for default profile. It is set in ``Connection`` category, with the parameters -named ``JabberID`` (be careful with the case):: - - $ jp param get Connection JabberID - -Get the type of the ``check_certificate`` parameters in ``Connection`` category:: - - $ jp param get Connection check_certificate -a type - -Get the constraint of the ``Priority`` parameters in ``Connection`` category:: - - $ jp param get Connection Priority -a constraint - -set -=== - -As expected, this command set a SàT parameter. The ``category``, ``name`` and ``value`` -are needed as positional arguments. - -``--security-limit SECURITY_LIMIT`` can be used if you want an update to be rejected if -the parameter is not modifiable with this limit. This can be useful if you use ``jp`` from -an external tool and you want to limit damage risks, or for testing purpose. - -examples --------- - -Use Markdown_ syntax for composition (e.g. for editing blog posts):: - - $ jp param set Composition Syntax markdown - -Try to change jid of the profile with a low security limit, this command should fail:: - - $ jp param set --security-limit 0 Connection JabberID some_random_jid@example.org - -.. _Markdown: https://daringfireball.net/projects/markdown/ - -.. _jp-param_save: - -save -==== - -Save the parameters structure to an external files. The parameters are saved as XML. The only -expected argument is the path to the destination file. - -.. note:: - - it's the parameters structure and not the parameters values which are saved. This is - low level method and most end users won't probably need it - -example -------- - -Save parameters structure to ``~/parameters.xml``:: - - $ jp param save ~/parameters.xml - -.. _jp-param_load: - -load -==== - -Load and merge the parameters structure from external XML files. The only expected -argument is the path to the source file. - -.. note:: - - it's the parameters structure and not the parameters values which is loaded and merged. - This is low level method and most end users won't probably need it - -example -------- - -Load and merge parameters structure from ``~/parameters.xml``:: - - $ jp param load ~/parameters.xml
--- a/doc/jp/ping.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ -========================================= -ping: get response time of an XMPP entity -========================================= - -``ping`` is more or less the equivalent of the command of the same name on most OSes, but -for XMPP. It send a `XEP-0199`_ PING and wait for the answer. When (and if) received, the -time to receive the answer is shown, else the time to receive the error message is shown. -This can be helpful to quickly test the connection with the server or a device. - -If you need to get only the response time (without text around), you may use ``-d, ---delay-only``. - -.. _XEP-0199: https://xmpp.org/extensions/xep-0199.html - -example -------- - -Get reponse time of a server:: - - $ jp ping example.org
--- a/doc/jp/pipe.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ -================================================== -pipe: send/receive data stream through shell pipes -================================================== - -``pipe`` commands allow you to send or receive data stream through a Unix shell pipe. -Salut à Toi will create a network connection (using XMPP and Jingle) between you an your -contact. - -in -== - -Receive data stream. Data will be send to stdout, so it can be piped out or simply print -to the screen. You can specify bare jids of entities to accept stream for, by default all -streams are accepted. - -example -------- - -Receive a video stream, and redirect it to mpv_ so show the video:: - - $ jp pipe in | mpv - - -.. _mpv: https://mpv.io/ - -out -=== - -Send data stream. Data comes from stdin, so you may use pipe in something or just write -some text. - -The only expected argument is the full jid of the device where the stream must be piped -out. - -example -------- - -Send a video to louise:: - - $ jp pipe out louise@example.org/sat < some_video.webm - -Send output from ``cal`` command to louise:: - - $ cal | jp pipe out louise@example.org/sat
--- a/doc/jp/profile.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,194 +0,0 @@ -============================= -profile: SàT profile handling -============================= - -Profiles are the names associated with accounts in SàT, for more informations you can -check :ref:`glossary`. The `profile` commands help you create/delete/modify and manage -profiles. - - -connect -======= - -Unsurprisingly this command connects your profile, i.e. log-in your XMPP account. This -command uses :ref:`jp-common_profile` common commands, so you can use either ``-c, ---connect`` to connect to XMPP server, or ``--start-session`` if you want to start SàT -profile session without connecting to XMPP server (for instance if you want to modify -parameters without connecting to XMPP server). - -Note that :ref:`jp-common_profile` common commands are available in commands needing a -connected profile, ``jp profile connect`` is interesting if you only want to connect your -profile/start a session. - -example -------- - -Connect the default profile:: - - $ jp profile connect -c - - -disconnect -========== - -Disconnect your profile from XMPP server. There is no option beside the -:ref:`jp-common_profile` common options. - -example -------- - -Disconnect the profile ``pierre``:: - - $ jp profile disconnect -p pierre - - -create -====== - -Create a new SàT profile. The only mandatory argument is the profile name, but you'll -probably want to associate an XMPP jid with ``-j JID, --jid JID`` and a profile password -with ``-p PASSWORD, --password PASSWORD``. By default, profile password will be used for -XMPP password (see note below), but you may specify XMPP password with ``-x PASSWORD, ---xmpp-password PASSWORD``. - -SàT is also capable to manage components, which can be seen as XMPP server independent -plugins. To create a component profile, you'll have to use ``-C COMPONENT, --component -COMPONENT`` where ``COMPONENT`` is the component entry point (check the documentation of -the component that you want to use to get its entry point). - -If you want a profile to connect automatically on backend startup (notably useful for -components), you can use the ``-A [{true,false}], --autoconnect [{true,false}]`` argument. - -.. note:: - - profile password and XMPP password are not the same: the profile password is the - password of your SàT profile, while the XMPP password is the one checked by your XMPP - server. If specify a jid with ``--jid`` and you don't specify an XMPP password, the - profile password will be used by default. - - The reason to have distinct password is that you may use a different password for - profile, including an empty one if you want SàT to connect your profile without - having to enter a password. Also the XMPP password is encrypted in database using the - profile password (which is not stored in database, only a hash is kept). - - -.. note:: - - passwords in jp are currently specified directly on the command-line and not prompted, - this is not safe from a security point of view as people can see it on the screen, it - may stay in your shell history, or visible on process list. Keep that in mind if you're - in a public environment or on a public machine. This will be improved for SàT 0.8. - -examples --------- - -Nestor wants to create a profile for its account on ``example.org``, he specifies a -profile password only, so it will also be used as the XMPP password:: - - $ jp profile create nestor -j nestor@example.org -p some_password - -Create a component profile for the file sharing component (whose entry point is -``file_sharing``). The jid of the service is specified with ``--jid`` (note that we don't -use a node as it is a jid of a component) and the ``--xmpp-password`` is the shared -secret. Here the profile password is kept empty to not have to enter manually the XMPP -password each time we connect the service:: - - $ jp profile create file_sharing -j files.example.org -p "" --xmpp-password - some_shared_secret -C file_sharing - - -default -======= - -This command simply prints the default profile (i.e. the profile used when none is -specified with ``-p PROFILE, --profile PROFILE``). The default profile is either the first -one that you've created, or the one you have explicitly set as default. - -example -------- - -Print default profile:: - - $ jp profile default - - -delete -====== - -Delete a profile and all its associated data. This delete the SàT profile and associated -data (i.e. local data), but doesn't request the XMPP server to delete anything. - -By default a confirmation is requested, use ``-f, --force`` to avoid it (be cautious with -this option). - -example -------- - -Delete the profile of Pierre:: - - $ jp profile delete pierre - - -info -==== - -Display information on a profile. For now, only the registered jid is shown, and -optionally the XMPP password. To display the XMPP password, use ``--show-password`` but be -careful that nobody can see your screen, as **this password will be shown in clear text**. - -example -------- - -Show jid and XMPP password for default profile:: - - $ jp profile info --show-password - - -list -==== - -Show all profiles. You can use ``-c, --clients`` to show only client profiles, and ``-C, ---components`` to show only component profiles. - -example -------- - -Show all profiles:: - - $ jp profile list - - -modify -====== - -Update an existing profile. You can use this command to change profile password (with ``-w -PASSWORD, --password PASSWORD``) or even disable it (with ``--disable-password``, this is -equivalent to using an empty profile password ; be cautious with this option, see the note -below). - -With ``-j JID, --jid JID`` and ``-x PASSWORD, --xmpp-password PASSWORD`` you can change -XMPP jid and password. - -This command can also be used to select the default password, use the ``-D, --default`` -flag for that. - -.. note:: - - Be cautious with ``--disable-password`` that means that no password will be needed with - any frontend of SàT to use this profile, and that XMPP password will be easy to - retrieve for anybody having an access to the machine where SàT is installed - -examples --------- - -Pierre has changed server, he can update his jid and password like this:: - - $ jp profile modify -p pierre -j pierre@example.org -x new_password - -Use ``louise`` as default profile:: - - $ jp profile modify -p louise -D - -Disable profile password for default profile (be cautious, see the note above):: - - $ jp profile modify --disable-password
--- a/doc/jp/pubsub.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,361 +0,0 @@ -.. _jp-pubsub: - -========================= -pubsub: PubSub management -========================= - -PubSub commands are low level command to handle a PubSub Service. -They are using the generic pubsub arguments - -For most of those commands, :ref:`pubsub_common` commands are used to specify the -destination item. - -set -=== - -Publish a pubsub item. - -``stdin`` is used to get the raw XML of the payload of the item to publish. - -``-f KEY VALUE, --field KEY VALUE`` can be used to specify publish options, i.e. option -which must be set if the node already exists, or used if the node is to be created, see -`XEP-0060 §7.1.5`_ for details. - -In the same way as for :ref:`jp-pubsub_node_create`, ``-F, --full-prefix`` can be used if -you need to specify the full option name. - -.. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options - -example -------- - -Create an item with a custom note XML:: - - $ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | jp pubsub set -n "notes" - -get -=== - -Retrieve items from specified node. Default output is prettified and highlighted XML. - -example -------- - -Retrieve the last 5 notes from our custom notes node:: - - $ jp pubsub get -n notes -m 5 - -delete -====== - -Delete an item from a node. If ``-N, --notify`` is specified, subscribers will be notified -of the item retraction. - -By default a confirmation is requested before deletion is requested to the PubSub service, -but you can override this behaviour by using ``-f, --force`` option. - -example -------- - -Delete item with id ``123456`` from a node:: - - $ jp pubsub delete -n test_node -i 123456 - -edit -==== - -Edit the raw XML of an item payload using your local editor (the one set in ``$EDITOR``). - -If you don't change anything or publish an empty blog post, the edition will be cancelled. - -:ref:`draft_common` commands can be used. - -example -------- - -Edit the last note in our custom node:: - - $ jp pubsub edit -n notes -L - -subscribe -========= - -Subscribe to a node. - -Subscription is used to get notifications from the node in case of new/updated item or -deletion. - -example -------- - -Subscribe to an information blog:: - - $ jp pubsub subscribe -n informations -s pubsub.example.net - -unsubscribe -=========== - -Unsubscribe from a node. - -example -------- - -Unsubscribe from an information blog:: - - $ jp pubsub unsubscribe -n informations -s pubsub.example.net - -subscriptions -============= - -Retrieve subscriptions for all nodes on a service. - -``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if -it has subscription with multiple subIDs). - -example -------- - -Retrieve all subscriptions on a pubsub service:: - - $ jp pubsub subscriptions -s pubsub@example.net - -affiliations -============= - -Retrieve affiliations for all nodes at a service. - -``-n NODE, --node NODE`` can be used to request affiliation for a specific node. - -examples --------- - -Retrieve all affiliations at a pubsub service:: - - $ jp pubsub affiliations -s pubsub@example.net - -Retrieve affiliation for the ``notes`` node:: - - $ jp pubsub affiliations -s pubsub@example.net -n notes - -search -====== - -Search items corresponding to one or more filter(s). - -``search`` will check all items (or some of them according to options used) from one or -several nodes (several nodes can be checked if recursion is used, see below). For each -item the given filters will be checked, and all corresponding items will be returned. - -This is a resource intensive method (both for server and client), use with caution, and -use MAM to do searching when suitable. - -filters -------- - -To do a search you one or more filters. Filters are checked in the order in which they are -specified. You can use 4 kinds of filters: - -``-t TEXT, --text TEXT`` - do a full-text search. If *TEXT* is appearing anywhere in the item (including in XML - tags or arguments), the item is selected - -``-r EXPRESSION, --regex EXPRESSION`` - do a regular expression search. `Python standard re module`_ is used internally, so you - can use its syntax. - -``-x XPATH, --xpath XPATH`` - use an `XPath version 1.0`_ expression to filter the query. You can have a look at - `Wikipedia XPath page`_ for a user friendly introduction. - -``-P PYTHON_CODE, --python PYTHON_CODE`` - use a Python expression to do a test. The expression must return a boolean (``True`` to - keep item, ``False`` otherwise). From within the Python expression 3 variables are - defined: ``item`` which contain the raw item as a string, and ``item_xml`` which is the - parsed XML as an lxml ``etree.Element`` and ``etree`` which is the ``lxml.etree`` module. - -.. _Python standard re module: https://docs.python.org/3.7/library/re.html -.. _XPath version 1.0: https://www.w3.org/TR/1999/REC-xpath-19991116/ -.. _Wikipedia XPath page: https://en.wikipedia.org/wiki/XPath - -filter modifiers ----------------- - -Before each filter you can specify one or more filter modifiers. A modifier will change -filter behaviour, it's a flag which can be used either without argument (then it will -activate the flag), or with an explicit boolean value (i.e. ``true`` or ``false``). - -The available filters are: - -``-C [BOOLEAN], --ignore-case [BOOLEAN]`` - (don't) ignore case. Filters are normally case sensitive, this modifier change this - behaviour. - -``-I [BOOLEAN], --invert [BOOLEAN]`` - (don't) invert effect of following filters. This is applying a logical ``NOT`` to the - filter. This means that instead of keeping item matching the filter, it will keep the - items which are **not** matching the filter. - -``-A [BOOLEAN], --dot-all [BOOLEAN]`` - (don't) use `DOTALL`_ option for regex. This filter only makes sense before a - ``--regex`` expression. - -``-k [BOOLEAN], --only-matching [BOOLEAN]`` - (don't) keep only the matching part of the item. Normally the whole item is returned, - with this flag, only the part matching the filters are kept. - -.. _DOTALL: https://docs.python.org/3.7/library/re.html#re.DOTALL - -actions -------- - -Once filters are set, you may indicate what do to with the found items. By default they -are printed, but you can also use an other jp command, or even an external tool. - -The following actions are available: - -``print`` (default) - pretty print the found items. - -``exec`` - use the given jp command on each found item. Everything after the ``exec`` is used to - indicate the command and arguments to use (you must not specify ``jp``, use the command - directly). The service, node and item will be set to match the found item. - -``external`` - pipe the raw XML of each item to the given command. Everything after the ``external`` - action is used to indicate the command and arguments to use. - -recursive search ----------------- - -By default, only items in the given node will be filtered, but if you specify a recursion -depth > 0 (using ``-D MAX_DEPTH, --max-depth MAX_DEPTH``), every node linked in item will -be checked too, then node linked in linked item and so on until depth level is reached. - -For instance, if you want to find all comments of a blog node containing an http(s) link, -you can do that:: - - $ jp pubsub search -n urn:xmpp:microblog:0 -s user@example.net -D 1 -r 'https?://' - -examples --------- - -Finding all items containing the text "something interesting" in personal blog:: - - $ jp pubsub search -n urn:xmpp:microblog:0 -M -1 -t "something interesting" - -Find which blog items in the last 20 have a body with less than 200 characters (note that -body can be either ``<title>`` or ``<content>``, see `XEP-0277`_ for details). Here we use -a python expression on the text of the body to count the number of characters:: - - $ jp pubsub search -n urn:xmpp:microblog:0 -M 20 --python "len((item_xml.find('.//{http://www.w3.org/2005/Atom}content[@type=\"text\"]') or item_xml.find('.//{http://www.w3.org/2005/Atom}title[@type=\"text\"]')).text) < 200" - -Find items published by ``toto@example.net`` among last 30 on a blog node, and use -``pubsub blog`` command to retrieve id and title. We use ``-N`` to specify the ``pubsub`` -namespace which is used in the XPath expression, then we use ``exec`` to run ``blog get -k -title -k id`` on found items:: - - $ jp pubsub search -n some_blog_node -s pubsub.example.net -M 30 -N pubsub http://jabber.org/protocol/pubsub -x '/pubsub:item[starts-with(@publisher, "toto@example.net")]' exec blog get -k title -k id - -Find items which have **NOT** a title among last 30 items in our personal blog. As -explained in `XEP-0277`_ Atom's ``<title>`` is always used (even if there is only a body -and no title), so we actually look for items without ``<content>``. We do that with an -XPath looking for this ``atom:content`` element, then we use the ``-I [BOOLEAN], --invert -[BOOLEAN]`` to filter out elements which match.:: - - $ jp pubsub search -n urn:xmpp:microblog:0 -M 30 -I -x //atom:content -N atom http://www.w3.org/2005/Atom - -Display authors names from last 10 items and their comments, using the ``-k [BOOLEAN], ---only-matching [BOOLEAN]`` modifier to only display the data we need. We use ``-D 1`` to -do a recursive search of level 1, which will also look into comments nodes (using last 10 -items there too):: - - $ jp pubsub search -n urn:xmpp:microblog:0 -M 10 --only-matching -x //atom:author/atom:name -N atom http://www.w3.org/2005/Atom -D 1 - -.. _XEP-0277: https://xmpp.org/extensions/xep-0277.html - -transform -========= - -Modify items using an external command. - -``transform`` will retrieve requested items, and will send each of them to the standard -input (stdin) of the specified command. The output of the command will be used, it can be -3 things: - -- a raw XML of the modified item, in which case the item will be republished -- the string ``SKIP``, in which case the item will be ignored -- the string ``DELETE``, in which case the item will be retracted - -By default a dry run is done, which means that no item is modified or deleted. To actually -do the transformation, you have to use ``--apply`` argument. - -If you have to modify the ``publisher`` of an item, you need specific privileges. The -``--admin`` allows you do to that, but it must be supported by your PubSub service -(currently only ``SàT PubSub`` supports this non standard feature). - -To modify all items of a node, use the ``-A, --all`` option. This will use `RSM`_ -repetitively until all items are treated. Of course that means that your PubSub service -must support RSM. The items being republished, they will reappear on top of your node, -that's why it is recommended to use ``--order-by creation`` option when supported by the -service, to keep consistent order and avoid transforming the same items several times. - -If the command you're using exit with a non zero code, the process will stop. Use ``-I, ---ignore_errors`` if you want to continue transformation even if an non zero code is -returned. - -.. _RSM: https://xmpp.org/extensions/xep-0059.html - -example -------- - -Imagine that you want to replace all occurrences of "sàt" by "Salut à Toi" in your personal blog. You first create a Python script like this: - -.. sourcecode:: python - - #!/usr/bin/env python3 - - import sys - item_raw = sys.stdin.read() - if not "sàt" in item_raw: - print("SKIP") - else: - print(item_raw.replace("sàt", "Salut à Toi")) - -And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make is executable -with ``chmod +x ~/expand_sat.py``). - -To be sure it's safe, you can first do a dry-run and check the result:: - - $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py - -Once you have checked that you have the expected behaviour, you can apply the -transformations:: - - $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py - -And that's it. You can use the same technique for more complex transformations, including -modifying the XML (with Python, you can easily do that with standard -``xml.etree.ElementTree`` module or with ``lxml.etree``). - -uri -=== - -Build an XMPP URI linking to a PubSub node or item. - -example -------- - -Build a link to personal blog:: - - $ jp pubsub uri -n urn:xmpp:microblog:0 - -node -==== - -Subcommands for node management. Please check :ref:`jp-pubsub_node`. - -hook -==== - -Subcommands for hooks management. Please check :ref:`jp-pubsub_hook`.
--- a/doc/jp/pubsub_hook.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,96 +0,0 @@ -.. _jp-pubsub_hook: - -==================================== -pubsub/hook: PubSub hooks management -==================================== - -``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks -are user actions launched on specific events. - -3 types of hooks can be used: - -``python`` - A Python module is expected as argument. The module must be available in Python path, - and it must have a ``hook`` function. - -``python_file`` - A path to a Python script is expected as argument. The script must contain a ``hook`` - function. - -``python_code`` - Python code which will be directly executed. 3 variables will be set: ``host`` which - contain the main SàT instance, ``client`` which contain the session attached to the - profile, and ``item`` which contain the item attached to the event. - -.. note:: - - Hooks are executed in SàT context, and must be asynchronous. If they block, the whole - SàT execution will be blocked. They have access to everything, so don't run a code that - you don't absolutely trust. - -.. note:: - - Only ``python_file`` type is currently implemented - -.. note:: - Hook is an experimental feature, the way to use it may change in the future. - -create -====== - -Create a hook of given type. Type is specified with ``-t {python,python_file,python_code}, ---type {python,python_file,python_code}`` and a positional arguments is expected, which -depends on the chosen type. - -By default the hook is temporary (it will be lost if the profile is disconnected), but you -can make is persistent accross reconnexions if you use the ``-P, --persistent`` argument. - -example -------- - -Install a persistent hook on blog node, using the Python script named -``do_something_neat.py`` in ``$HOME`` directory:: - - $ jp pubsub node hook create -n urn:xmpp:microblog:0 -t python_file --persistent ~/do_something_neat.py - -delete -====== - -Delete one hook or all of them. To delete a hook, specify its type and argument (the that -you have used with ``create``). If you use empty ``--type`` and ``--arg`` all hooks will -be removed. - -example -------- - -Delete the ``do_something_neat.py`` hook:: - - $ jp pubsub node hook delete -n urn:xmpp:microblog:0 -t python_file --arg ~/do_something_neat.py - -list -==== - -List registered hooks. The output will give the following informations: - -service - PubSub service on which the hook is attached. - -node - PubSub node on which the hook is attached. - -type - hook type - -arg - hook arguments (dependant of hook type) - -persistent - boolean indicating is the hook persist accross sessions. - -example -------- - -Get PubSub hooks registered for this profile in JSON:: - - $ jp pubsub hook list -O json -
--- a/doc/jp/pubsub_node.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,126 +0,0 @@ -.. _jp-pubsub_node: - -==================================== -pubsub/node: PubSub nodes management -==================================== - -``node`` is a subcommands grouping all PubSub commands related to node management. For -details on ``pubsub`` command itself, refer to :ref:`jp-pubsub`. - -info -==== - -Get settings of the node. Use ``-k KEYS, --key KEYS`` to select data to print. - -examples --------- - -Get informations on our personal microblog node:: - - $ jp pubsub node info -n urn:xmpp:microblog:0 - -Only print ``access_model`` and ``publish_model``:: - - $ jp pubsub node info -n urn:xmpp:microblog:0 -k access_model -k publish_model - -.. _jp-pubsub_node_create: - -create -====== - -Create a node. Node configuration can be specified using ``-f KEY VALUE, --field KEY -VALUE`` where ``KEY`` is a pubsub option. By default the ``pubsub#`` prefix will be -appended, as it is used with standard options (see `XEP-0060`_ for more details); to -change this behaviour, use the ``-F, --full-prefix`` flag. - -.. _XEP-0060: https://xmpp.org/extensions/xep-0060.html - -example --------- - -Create a node called ``notes`` with a ``whitelist`` access model (so only you and people -you may authorize later can access it):: - - $ jp pubsub node create -n notes - -purge -===== - -Remove all items from a node (but don't delete the node). - -A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. - -example -------- - -Remove all items from a blog comments node (in other words, removing all comments while -letting the node so people can add new comments):: - - $ jp pubsub node purge -n "urn:xmpp:microblog:0:comments/123-456-789" - -delete -====== - -Delete a node (note that this will delete definitively all items that where published to -this node). - -A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. - -example -------- - -Delete the ``temporary_notes`` node:: - - $ jp pubsub node delete -n temporary_notes - -set -=== - -Update a node configuration. - -Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` argument -where ``KEY`` is a PubSub option. If ``KEY`` doesn't start with ``pubsub#`` prefix, it is -added automatically, except if ``-F, --full-prefix`` argument is used (in which case the -``KEY`` is used as specified. - -example -------- - -Make the ``public_notes`` node accessible to the world:: - - $ jp pubsub node set -n public_notes -f access_model open - -import -====== - -Import a raw XML containing items to create in the node. The path to the XML file is used -as positional argument. - -The XML file must contain full `<item>` element for each item to import. The output of ``pubsub get`` can be used directly. - -If you want to change publisher of one or more items (i.e. if you want to use an other ``jid`` than the jid of the profile as publisher), you must use the ``--admin`` arguments. This needs a PubSub service supporting this feature (and you must of course be an administrator of this service). The new publisher must be allowed to publish to the node. - -example -------- - -Import a node backup which has previously been saved using ``jp blog get -M -1 -n -some_node > some_node_backup.xml``:: - - $ jp pubsub node import -n some_node ~/some_node_backup.xml - -.. note:: - - If your node is big, -M 1 option is not adapted as it will get all items at once and - may be blocked by your server stanza size limit. The possibility to use RSM to - retrieve all items by pages is planned in a future version. - -affiliations -============ - -Subcommands for node affiliations management. Please check :ref:`jp-pubsub_node_affiliations`. - -subscriptions -============= - -Subcommands for node subscriptions management. Please check -:ref:`jp-pubsub_node_subscriptions`.
--- a/doc/jp/pubsub_node_affiliations.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,40 +0,0 @@ -.. _jp-pubsub_node_affiliations: - -======================================================= -pubsub/node/affiliations: nodes affiliations management -======================================================= - -``affiliations`` is a subcommand handling the affiliations of a node (not to be confused -with ``pubsub affiliations`` which handle the affiliations of a PubSub service). - -get -=== - -Retrieve entities affiliated to this node and their role. - -example -------- - -Get affiliations of a node:: - - $ jp pubsub node affiliations get -n some_node - -set -=== - -Set affiliation of an entity on a node. Affiliations are specified with ``-a JID -AFFILIATION`` argument. Check `XEP-0060 affiliations`_ for allowed values for -``AFFILIATION``. Use ``none`` to remove an affiliation. - -.. _XEP-0060 affiliations: https://xmpp.org/extensions/xep-0060.html#affiliations - -example -------- - -If we have a whitelisted node ``some_whitelisted_node``, we can allow -``louise@example.net`` to publish on it (by setting her role as ``publisher``), and -``pierre@example.net`` to access it (by setting his role as ``member``) using the -following command:: - - $ jp pubsub node affiliations set -n some_whitelisted_node -a louise@example.net - publisher -a pierre@example.net member
--- a/doc/jp/pubsub_node_schema.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ -.. _jp-pubsub_node_schema: - -========================================= -pubsub/node/schema: nodes schema handling -========================================= - -``node schema`` is an experimental feature to associate a data form with a PubSub node, and -reject items not following this form. This feature is currently only available with SàT -PubSub. - -Those commands can only be used by an owner of the node. - -set -=== - -Set the schema of a node. The raw schema is written directly as positional argument. - -example -------- - -Set the schema for tickets node using the file ``tickets_schema.xml`` from ``$HOME`` -directory. Shell substition is used here to put the content of the file in the positional -argument:: - - $ jp pubsub node schema set -n org.salut-a-toi.tickets:0 -s pubsub.example.org "$(<~/test_schema.xml)" - - -edit -==== - -Edit the schema of a node using your local editor (the one set in ``$EDITOR``). - -If you don't change anything or publish an empty schema, the edition will be cancelled. - -:ref:`draft_common` commands can be used. - -example -------- - -Edit the tickets node schema:: - - $ jp pubsub node schema edit -n org.salut-a-toi.tickets:0 -s pubsub.example.org - - -example -------- - -get -=== - -Retrieve schema of a node. - -example -------- - -Get schema of tickets and save it to a file named ``tickets_schema.xml`` in ``$HOME`` -directory:: - - $ jp pubsub node schema get -n org.salut-a-toi.tickets:0 -s pubsub.example.org > ~/tickets_schema.xml
--- a/doc/jp/pubsub_node_subscriptions.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ -.. _jp-pubsub_node_subscriptions: - -======================================================== -pubsub/node/affiliations: nodes subscriptions management -======================================================== - -``subscriptions`` is a subcommand handling the subscription to a node. - -Those commands can only be used by an owner of the node. - -get -=== - -Retrieve subscriptions to a node. - -example -------- - -Get subscription from ``some_node``:: - - $ jp pubsub node subscriptions get -n some_node - -set -=== - -Set subscriptions to a node. Subscriptions are specified with ``-S JID [SUSBSCRIPTION] -[JID [SUSBSCRIPTION] ...], --subscription JID [SUSBSCRIPTION] [JID [SUSBSCRIPTION] ...]`` -where ``JID`` is the jid of the entity to change subscription state, and ``SUBSCRIPTION`` -is a subscription state (on of ``subscribed``, ``pending``, ``none``) as specified in -`XEP-0060 Subscription State`_. If ``SUBSCRIPTION`` is not specified, it default to -``subscribed``. - -.. _XEP-0060 Subscription State: https://xmpp.org/extensions/xep-0060.html#substates - -example -------- - -Subscribe Louise with her new address at ``louise@example.org`` and remove her -subscription from old ``louise@example.com``:: - - $ jp pubsub node subscriptions set -n some_node -S louise@example.org subscribed louise@example.com none - -
--- a/doc/jp/roster.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,145 +0,0 @@ -================================ -roster: manager an entity roster -================================ - -"Roster" is the name used in XMPP for the contact list. In addition to list of contacts, -you have also data like subscription information or groups associated to a contact. - -Groups are simple strings associated to one or more contacts (e.g. "friends" or "family"). - -Subscription is the mechanism to get presence information of an entity. When you add a -contact to your roster, most XMPP clients also do a presence subscription request, than -the entity may accept or deny. If a presence subscription is accepted, the subscribed user -can see when the other entity is online, and its presence status. - -get -=== - -Show the current roster. By default only a display name and JIDs are displayed, but you -can increase verbosity to also display groups, or all other metadata. - -The short name shown next to jid is either the ``name`` specified in roster, or the node -part of the jid. If none of them exist, only the entity JID is shown. - -The following metadata may be displayed: - -groups - group the entity belong too -ask - true if a presence subscription request has been sent (but not answered yet) -from - the contact has a subscription to user presence (i.e. your contact can see when you're - online and your presence status) -to - the user has a subscription to the contact presence (i.e. you can see when you're - contact is online and his/her presence status) - -examples --------- - -Get roster of default profile and display groups:: - - $ jp roster get -v - -Get roster of default profile and display all metadata:: - - $ jp roster get -vv - -Get roster or default profile and show the result in JSON:: - - $ jp roster get -O json - -set -=== - -Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being -the user chosed name to use with a contact. - -By default, values are appended, i.e. if ``name`` is not set it won't delete existing one, -and ``groups`` are appended to existing one. However, if you use the ``-R, --replace`` -option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n -NAME, --name NAME`` option, the former one will be deleted, and any former group no added -using ``-g GROUP, --group GROUP`` will be removed). - -examples --------- - -Set a name used to privately identify your contact Louise:: - - $ jp roster set -n Enjolras louise@example.net - -Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``:: - - $ jp roster set --replace -g friends -g housemates pierre@example.net - -delete -====== - -Remove an entity from roster. - -examples --------- - -Remove John from your roster:: - - $ jp roster delete john@example.net - -stats -===== - -Show some statistics about the profile roster. The number of contacts per server is shown, -with a percentage of contacts on this server compared to the total number of contacts. -This can notably be helpful to see if there is a concentration of your contacts in a -specific server or gateway. - -Other more or less useful numbers are shown, they are self explaining. - -example -------- - -Get statistic for the default profile:: - - $ jp roster stats - -purge -===== - -This command is used to remove from the roster all contacts which have no subscription or -only partial subscription. - -By default, only contacts without subscription at all are removed. With ``--no_from`` you -also remove contacts which have no subscription to you (but you have a subscription to -them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but -who are subscribed to you). - -example -------- - -Remove all contacts from default profile which have no subscription at all or from which -the default profile is not subscribed to:: - - $ jp roster purge --no_to - -resync -====== - -SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on -client connection. This means that once the roster has been retrieved, on each following -connection, only the difference of contacts (i.e. which new or removed contacts) is -received. - -This command does a full resynchronisation of the roster, or in other words it requests -the whole roster and save it, replacing the list built with versioning. ``resync`` is -mostly useful for developers and end-user should not need this command, as roster -versioning is supposed to work fine and the roster should be synchronised correctly on -startup. But if for any reason you suspect that your current roster list is corrupted, you -may use it to be sure that a full resynchronisation is done. - -.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6 - -exemple -------- - -Do a full resynchronisation of default profile's roster:: - - $ jp roster resync
--- a/doc/jp/shell.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,208 +0,0 @@ -======================== -shell: use SàT with REPL -======================== - -``shell`` launch a read–eval–print loop (REPL) with some helpers to launch jp commands. -This is useful if you are willing to a session when you'll use several commands in a row -(for e.g. to inspect something on a PubSub service). - -start the shell -=============== - -To start the shell, you just have to enter ``jp shell``. You can eventually specify a -profile to use an other one than the default one by entering ``jp shell -p -<some_profile>``. - - -.. _jp-shell_use: - -use the shell -============= - -Once in the shell, you can launch a command by entering it as usual (without having to -specify ``jp``). For instance to get last 2 blog posts from your personal blog, you just -have to enter:: - - > blog get -m 2 - -There are 2 kinds of commands in the shell: - -- **shell commands** which are command to manipulate the shell itself -- **jp commands** which are the classic commands that you use with jp - -The most important thing to remember is that you can use ``?`` (or ``help`` which is -equivalent) to get the list of commands (shell + jp), and ``?<command>`` (or ``help -<command>``) to get information on a shell command. For jp commands, you can use the usual -``--help`` argument. - -You may move in the commands hierarchy using ``cmd`` which can be seen as something -roughly equivalent to ``cd`` for the filesystem. for instance if you know you'll work with -XMPP blogs, you can enter:: - - > cmd blog - -Then you'll be in the blog hierarchy, you can check that by entering ``?``. From there you -can use blog commands directly, like in this example to retrieve last 2 blog posts:: - - blog> get -m 2 - -You can even go further, e.g. if you know that you'll do several ``get`` command (in this -can you'll only have to specify the arguments of ``get``):: - - blob> cmd get - blog/get> -m 2 - -You can use ``/`` with ``cmd``, including as first character to indicate that you want to -start from root:: - - blog/get> cmd /pubsub - pubsub> cmd node/info - -Similarly, you can use ``..`` to move to parent command:: - - pubsub/node/info> cmd .. - -One of the interesting feature of shell is that you can fix an argument, i.e. indicate -the value to use in the next commands. For instance if you're willing to work on a -specific node, you can set its value with ``use``:: - - blog> use node some_interesting_node - -Then you won't have to specify it anymore for each command. The name of the argument to -fix must be the long form. To check which arguments are fixed, just enter ``use`` without -argument. If an argument is fixed but not used in a command, it will be ignored. - -To clear a fixed argument, you have the ``use_clear`` command. To clear the ``node`` -argument set above, just enter:: - - blog> use_clear node - -Without argument, all fixed arguments will be cleared. - - -Shell commands -============== - -Below is a description of shell commands. - - -cmd ---- - -Move in the command hierarchy, this avoid to type again a command if you know you'll use -it several times. See jp-shell_use_ for explanation and examples - -do --- - -Launch a jp command. By default the command is launched if you enter directly its name and -arguments, but if a command or argument conflict with a shell command, the shell command -will be launched instead. The ``do`` command avoid such a situation by always launching a -jp command:: - - > do blog get -m 2 - -exit ----- - -Quit the shell (alias of ``quit``). - -help (alias ``?``) ------------------- - -Give information on available commands or on a specific command, see jp-shell_use_ for -more explanations. - -examples -^^^^^^^^ - -Get general help:: - - > ? - -Get help on ``do`` command:: - - > ?do - -quit ----- - -Quit the shell - -shell (alias ``!``) -------------------- - -Launch an external command. - -example -^^^^^^^ - -Print a calendar with ``cal``:: - - > !cal - -use ---- - -Fix the value of an argument, which will then be set for all following commands, see -jp-shell_use_ for more explanations. - -Without argument, show all fixed arguments - -examples -^^^^^^^^ - -Fix the PubSub node (the long name of the argument is used, so it will go to ``--node``):: - - pubsub> use node some_intersting_node - -Show all fixed arguments:: - - > use - -use_clear ---------- - -Unfix the value of an argument (i.e. use the normal default value). Without argument, -it unfixes all arguments. - -examples -^^^^^^^^ -Clear the node:: - - pubsub> use_clear node - -Clear all arguments:: - - > use_clear - -verbose -------- - -Without argument, show if verbose mode is activated. With an argument evaluating to a -boolean, activate or deactivate this mode. - -In verbose mode, the fixed arguments and the command launched are printed before launching -a jp command. - -examples -^^^^^^^^ - -Show if verbose mode is activated:: - - > verbose - -Activate verbose mode:: - - > verbose on - -version -------- - -Print current version of jp/Salut à Toi. - -whoami ------- - -Show the name of the connected profile (the one set with ``--profile`` when launching the -shell). This profile will be used as default profile.
--- a/doc/jp/ticket.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,72 +0,0 @@ -================================= -ticket: create and manage tickets -================================= - -Ticket is a generic tools to create items with metadata and states (where state can be -``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs -management. - -get -=== - -Retrieve one or more tickets and display them. A project may use magic string in README to -indicate PubSub service and node to use, in which case use just need to be in the -directory of the project. - -examples --------- - -Retrieve last 5 tickets (ordered by creation) from a project using magic string in README:: - - $ jp ticket get -m 5 -o creation - -Retrieve the ticket with id ``123`` on service ``pubsub.example.org``:: - - $ jp ticket get -s pubsub.example.org -i 123 - - - -import -====== - -Import tickets from an external source. This works in the same way as -:ref:`jp-blog_import`: you need to specify an importer and a data location. If you let -both positional argument empty, you'll get list of importers, if you specify importer but -not data location, you'll get a description on how the importer works. - -If you want to see a progress bar for the import, use the ``-P, --progress`` option, this -is recommended for most imports. - -Some importers may have specific option (check description for details), you can specify -them with ``o NAME VALUE, --option NAME VALUE`` - -When you import a ticket, the ticket will be created according to the schema of the PubSub -node. By default, the metadata of the original ticket will be put to the one of the same -name in the dest PubSub item. But of course the schema of your destination PubSub node may -differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD -DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done -(``IMPORTED_FIELD is the name of the field in the original ticket, while ``DEST_FIELD`` if -the name of the field in your node schema). - - -examples --------- - -Get list of ticket importers:: - - $ jp ticket import - -Get description of ticket importer for Bugzilla:: - - $ jp ticket import bugzilla - -Import tickets from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the -``pubsub.example.org`` PubSub service. We use default tickets node and want a progression -bar:: - - $ jp ticket import -P -s pubsub.example.org ~/bugzilla_export.xml - -Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to -the field ``assigned_to`` in our schema:: - - $ jp ticket import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml
--- a/doc/jp/uri.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,39 +0,0 @@ -================================ -uri: XMPP URI parsing/generation -================================ - -URI commands are helper to easily parse/build XMPP URIs. - -parse -===== - -Parse an XMPP URI, and print different parts. - -When possible, the ``type`` of URI is shown (e.g. ``pubsub``) and the ``sub_type`` (e.g. -``microblog``). - -The ``path`` is always displayed (see `RFC 5122 Path section`_ for details). - -If suitable, you'll also get data like ``node`` (for a PubSub URI). - -.. _RFC 5122 Path section: https://tools.ietf.org/html/rfc5122#section-2.4 - -examples --------- - -Parse a blog URI:: - - $ jp uri parse "xmpp:somebody@example.org?;node=urn%3Axmpp%3Amicroblog%3A0" - -build -====== - -Build an XMPP URI according to arguments. 2 positional arguments are expected: ``type`` -and ``path``. For now, only ``pubsub`` type is supported. - -examples --------- - -Build XMPP URI for a blog:: - - $ jp uri build pubsub somebody@example.org -f node urn:xmpp:microblog:0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/account.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,75 @@ +================================ +account: XMPP account management +================================ + +``account`` command help you to create or manage the XMPP account of a server, using +In-Band Registration (`XEP-0077`_). + +.. _XEP-0077: https://xmpp.org/extensions/xep-0077.html + +create +====== + +Create a XMPP account. You have to specify your jid and password as positional arguments. +By default the registration is done on ``localhost`` with default XMPP Client 2 Server +port (i.e. 5222), but you can specify other host/port using ``-H HOST, --host HOST`` and +``-P PORT, --port PORT``. You may also specify an e-mail address using ``-e EMAIL, --email +EMAIL`` (use of this data depend of the server implementation). + +By default, no SàT profile is created and associated to this new XMPP account, but you can +use ``-p PROFILE, --profile PROFILE`` if you are willing to have one. + +example +------- + +Create account for the new user Nestor at ``nestor@example.org`` and associate it with the +SàT profile ``nestor``:: + + $ li account create nestor@example.org some_password -p nestor + + +modify +====== + +Modify an existing XMPP account password. This will modify the XMPP account linked to the +given profile. + +.. note:: + + Only the XMPP password on the server is changed, not the one registered in the + parameter of SàT. You may have to update the parameter of your profile if the new + password doesn't correspond to your parameters one (you can do that with li param set + or with most SàT frontends in parameters). + +example +------- + +Change the XMPP password of the XMPP account of the default profile:: + + $ li account modify new_password + + +delete +====== + +Delete the XMPP account linked to the given profile from the XMPP server. Before using +this command, please be sure to understand well that **THIS WILL REMOVE THE WHOLE XMPP +ACCOUNT AND DATA FROM THE XMPP SERVER**. + +By default a confirmation is requested, you can do this without confirmation by using +``-f, --force``, however this is **NOT RECOMMENDED**, be sure to understand what you're +doing if you use this option (and be sure to spell correctly the profile, if you forget +the ``-p PROFILE, --profile`` argument for instance, this would delete entirely the +default profile). + +.. note:: + + Be extra careful with this command, as it will remove the whole account from the + server, and the associated data. + +example +------- + +Delete the XMPP account of Pierre, which is not on the local server anymore:: + + $ li account delete -p pierre
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/ad-hoc.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,120 @@ +======================= +ad-hoc: Ad-Hoc commands +======================= + +Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used +either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get +list of connected users, send a service announcement, restart parts of the server), or +execute about anything (e.g. control a physical robot with XMPP). + +run +=== + +Run an ad-hoc command. You may specify the node to run as positional argument, or let it +empty to list available commands. + +By default the commands from your server are used, but with ``-j JID, --jid JID`` you can +specify a different entity. + +You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and +``-S, --submit`` as many time as needed. ``--field`` expect a ``KEY`` which is the name +of the field to set. If you don't know which name to use, you can run the command to +automatise a first time manually with ``--verbose, -v`` flag, this will display fields +names when you have to fill them. + +Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then +if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and +so on as many times as you need. + +Don't forget that you can use your shell substitution capabilities if necessary, for +instance if you have a pre-registered announce to send. + +examples +-------- + +Get a list of available commands on your server to launch a command:: + + $ li ad-hoc run + +If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements +to online users. This can be useful to notify an imminent maintenance of the server. Here +we notify online users that the server will be shutdown in 30 min, using a shell +substitution capabilities with a pre-registered message in the file +``~/announces/maintenance_30.txt``, then we submit it:: + + $ li ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S + +Get your server uptime (if supported by your server):: + + $ li ad-hoc run uptime + +Run the commands available at the service with the jid ``someservice.example.org``:: + + $ li ad-hoc run -s someservice.example.org + +Run you server commands with verbosity so you get the name of the fields that you can fill +automatically later:: + + $ li ad-hoc run -v + +.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html + +list +==== + +List ad-hoc commands available at a service. + +examples +-------- + +List ad-hoc commands available at your server:: + + $ li ad-hoc list + +List ad-hoc commands available at a chat service:: + + $ li ad-hoc list -j conference.example.org + +remote +====== + +Create a remote control from launched media players. Ad-hoc commands to control the media +player will be added to your device, allowing anybody allowed (including yourself from an +other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc. + +To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can +specify who is allowed to control this media player with the following options: + +``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]`` + jids of entities allowed to control the media player + +``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]`` + groups (from your roster) allowed to control you remote + +``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]`` + groups (from your roster) which are **NOT** allowed to control your media player + +``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]`` + jids of entities which are **NOT** allowed to control your media player + +If you want the commands to run repeatedly (in opposition of stopping after first action +is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it. + +.. note:: + + SàT already creates automatically a remote control if it finds a media player. This + manual way to create a remote control predate the automatic remote control, and is + currently more flexible in that you can specify who can access the remote control + (automatic remote control is only accessible by the jid of the profile). + +examples +-------- + +Create a remote control for a running VLC instance:: + + $ li ad-hoc remote vlc -l + +Create a remote control for a running SMPlayer instance, and allowing anybody from your +``housemates`` group to use it:: + + $ li ad-hoc remote smplayer -g housemates -l
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/avatar.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,47 @@ +=============================== +avatar: retrieve/upload avatars +=============================== + +Avatars are images associated to an XMPP entity. Several XMPP extensions are in use, SàT +tries to hide the technical details so avatar are as easy as possible to manipulate for +end-user. + +get +=== + +Retrieve the avatar of the given entity. Entity jid is specified as positional argument. + +If an avatar is found, a path to its cached file is printed. Please note that this is the +cache used by all SàT ecosystem, **do not modify the cached image**. You may use it for +read-only access, or copy it if you want to modify the image. + +You may use the ``-s, --show`` argument to display the found avatar. The software used to +display the image can be specified in SàT configuration (cf. :ref:`configuration`), in the +``[li]`` section: the ``image_cmd`` setting let you specify the path to the software. If +``image_cmd`` is not used, ``li`` will try some common software, and if none is found, it +will try to open the image in a browser (which may sometimes result in using the default +image software of the platform). + +When available, cached avatar is returned by defaut. If you want to ignore the cache, use +the ``--no-cache`` option (of course this can result in more network requests). + +example +------- + +Get the avatar of ``louise@example.org`` and display it:: + + $ li avatar get --show louise@example.org + + +set +=== + +Upload and set the given avatar for the profile. The only required argument is the path to +the image to use as avatar. + +example +------- + +Set the avatar of the default profile:: + + $ li avatar set ~/photos/some_photo.jpg
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/blog.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,299 @@ +.. highlight:: sh + +================================ +blog: (micro)blogging management +================================ + +Blog commands are high level tools to handle an XMPP blog. +They are using the generic pubsub arguments + +set +=== + +publish a blog item. + +:ref:`pubsub_common` commands are used to specify the destination item. + +``stdin`` is used to get the body of the blog post. + +examples +-------- + +Create a blog post with a body, a subject, 2 tags, and with comments allowed:: + + $ echo "This is post body" | li blog set -T "This is a test message" -t test -t li -C + +Create a blog post with rich content using `markdown` syntax, and no subject:: + + $ echo "This is a **rich** body" | li blog set -S markdown + +get +=== + +get command retrieves one or more blog post(s) from specified location (by default the +personal blog of the profile). + +output can be customised to only retrieve some keys, or to use a specific template. For +instance, the following command retrieves only the title and publication date of the +personal blog of the profile:: + + $ li blog get -k title -k published + +:ref:`pubsub_common` commands are used to specify the blog location. + +examples +-------- + +Retrieve personal blog of the profile using `fancy` output with a verbosity of 1 (to show +publication date):: + + $ li blog get -O fancy -v + +Retrieve *title* and *publication date* of last 3 blog posts from the blog at +https://www.goffi.org:: + + $ li blog get -m 3 -u https://www.goffi.org -k title -k published + +Retrieve last 2 posts of personal blog, and output them in browser using default +template:: + + $ li blog get -m 2 -O template --oo browser + +.. _libervia-cli_blog_edit: + +edit +==== + +With edit command you can create a new blog post or modify an existing one using your +local editor (the one set in ``$EDITOR``). You'll edit 2 things: the body of the post, and +the metadata which contain things like title, comments infos, or tags. + +For some common editors (like **vim** or **Emacs**), the editor will be automatially +opened using a split screen with *body* in one side, and metadata on the other. If the +editor is not supported or doesn't support split screen, you'll edit first the *body*, then +the *metadata*. You can also specify editor and arguments in ``sat.conf``, see +`configuration <edit_conf_>`_ below + +If you don't change anything or publish an empty blog post, the edition will be cancelled. + +In the metadata (see `below <edit_metadata_>`_ for details), you can use ``"publish": +false`` to forbid the publication (or set it with ``--no-publish argument``). In this +case, when you'll save your modification and quit your editor, the blog post will not be +published but saved locally in a draft. To continue your work later, just start your +edition with the ``-D, --current`` option like this:: + + $ li blog edit -D + +Note that item location must be re-specified if it has been used to create the draft, so +you'll have to reproduce the arguments to specify service, node or item (or the URL), +other data like tags will be restored from draft file of metadata. + +You can specify the syntax by using ``-S SYNTAX, --syntax SYNTAX``. If not specified, the +syntax set in your parameters will be used. + +When you edit a blog post, it is often useful to activate the ``-P, --preview`` option, +this will launch a web browser and refresh the page each time you save a modification in +your editor. By default, the browser registered as default in your system will be used, +and a new tab will be opened on each modification. This is not ideal, and we recommand to +set you configuration to activate automatic refreshing of the page instead, see `preview +configuration <edit_preview_>`_ below to see how to do. + +.. note:: + + If --preview doesn't work, use ``li blog preview`` (see below) to get error messages. + On GNU/Linux, Be sure that inotify Python module is installed correctly. + +examples +-------- + +Edit a new blog post with comments on your personal blog, using default syntax and preview:: + + $ li blog edit -P --comments + +Modifiy a draft previously saved using the ``"publish": false`` metadata:: + + $ li blog edit -D + +Correct a typo in your last published blog post:: + + $ li blog edit --last-item + +Edit the blog item at an HTTPS URL using XHTML syntax:: + + $ li blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml + +Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that +https://example.net is a XMPP blog node):: + + $ li blog edit -u https://www.example.net + +.. _edit_metadata: + +metadata +-------- + +Metadata is set using a JSON object. The key you can use are: + +publish + boolean indicating if item can be published. Set to ``false`` if you want to work on a + draft and to avoid accidental publication. + +atom_id + atom entry identifier. This should not be modified manually. + +published + time of initial publication (unix time). This should not be modified manually. + +language + language of the content + +comments + array of URIs to the comments node, if any. + +tag + array of tags, if any + +author + human readable name of the entry author + +author_jid + jid of the author. This should notbe modified manually. + +author_jid_verified + true if the pubsub service confirmed that author_jid is the one of the publisher. It is + useless to modify this variable. + +title + the title of the message + +title_rich + the rich title of the message, in current text syntax. It will be automatically + converted to xhtml. + +.. _edit_conf: + +configuration +------------- + +editor +^^^^^^ + +Local editor used is by default the one set in ``$EDITOR`` environment variable, but you +can specify one in ``sat.conf``. To do so, you have to set the name of an editor +executable in the ``editor`` option in ``[li]`` section. + +You can specify the args to use by using ``blog_editor_args`` option. Use +``{content_file}`` to get the path of the main content file (the body of the blog post), +and ``{metadata_file}`` to get the path of the json metadata. + +.. sourcecode:: cfg + + [li] + editor = kate + blog_editor_args = {content_file} {metadata_file} + +.. _edit_preview: + +preview +^^^^^^^ + +To set the preview, you can use the options ``blog_preview_open_cmd`` and +``blog_preview_update_cmd`` in your ``[li]`` section. the former is the command to use to +open your browser when edition starts, and the later is the command to use when a +modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file. + +This can be used to activate automatic refreshing of the page. + +For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is +installed on your system, and enter the following lines in your ``sat.conf``: + +.. sourcecode:: cfg + + [li] + blog_preview_open_cmd = konqueror {url} + blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" + +For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the +following lines in your ``sat.conf``: + +.. sourcecode:: cfg + + [li] + blog_preview_open_cmd = firefox -new-tab {url} + blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" + +This *xdotool* technique can be adapted to other browsers. + +syntax extensions +^^^^^^^^^^^^^^^^^^ + +A dictionary with a mapping from syntax name to file extension can be used. This can be +useful to activate the right syntax highlighting in your editor. There is a default +mapping which can be overriden. + +The mapping is set in the ``syntax_ext_dict`` option of the ``[li]`` section of your +``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files +instead of the default ``.md``, you can use this: + +.. sourcecode:: cfg + + [li] + syntax_ext_dict = {"markdown": "markdown"} + +the first ``markdown`` is the name of the syntax (could be an other syntax like ``xhtml``), +while the second if the file extension. + +preview +======= + +This command will show the specified file in browser, and refresh it when changes are +detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be +used if you have already started an edition with ``li blog edit`` but forgot to use the ``-P, --preview`` arguments. + +example: +-------- + +Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``:: + + $ li blog preview ~/local/sat/blog/some_name/blog_something.md + +.. _libervia-cli_blog_import: + +import +====== + +With this command you can import an external blog in a XMPP blog at the specified pubsub +location. + +The import is done using an *importer* name and a *location* which depends of the importer +(it can be a path to a file, an URL to a blog, or something else). Let empty to get list +of importers, and specify only importer name to get its description. + +By default, found images are re-uploaded to XMPP server, if you want to keep original +URLs, use the ``--no-images-upload`` option. + +Alternatively, you can re-upload images except for a specific host with ``--upload-ignore-host UPLOAD_IGNORE_HOST``. The images for the specified host will keep there original URLs while other will be uploaded to XMPP server. + +You shoud specify original blog host using ``--host HOST`` argument, this is used notably +to reconstruct relative URLs of media. + +Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. + +examples: +--------- + +List available importers:: + + $ li blog import + +Get description of ``dotclear`` importer:: + + $ li blog import dotclear + +Import a Dotclear blog:: + + $ li blog import dotclear /path/to/dotclear.dump + +Import a Dotclear blog without uploading images:: + + $ li blog import --no-images-upload dotclear /path/to/dotclear.dump
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/bookmarks.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,98 @@ +============================ +bookmarks: get/set bookmarks +============================ + +Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons, +XMPP has several ways to handle bookmarks, and SàT handle them as transparently as +possible. + +With SàT there are 3 places where you can get/store your bookmarks: + +local + the bookmarks is stored only locally in the database of SàT. It won't be available to + other devices. +private + the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to + use this if PubSub storage is available +pubsub + the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to + store bookmarks. + +When possible, you can specify ``auto`` to let SàT choose the best location (i.e. +``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible). + +.. _XEP-0049: https://xmpp.org/extensions/xep-0049.html +.. _XEP-0223: https://xmpp.org/extensions/xep-0223.html + + +list +==== + +Get and print available bookmarks. You specify the location of the bookmarks to print +using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default +all bookmarks from all locations are printed. + +Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or +URLs. + +After printing the bookmarks location, the bookmarks will show the name and location (jid +for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if +autojoin is set. + + +examples +-------- + +Retrieve all MUC bookmarks:: + + $ li bookmarks list + +Retrieve all bookmarked URL stored in PubSub:: + + $ li bookmarks list -l pubsub -t url + + +remove +====== + +Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as +positional argument. If you are deleting an URL, you need to specify it with ``-t url`` + +By default a confirmation is requested, use ``-f, --force`` if you don't want it (with +usual caution). + +examples +-------- + +Delete the bookmark of a MUC room that you are not following anymore:: + + $ li bookmarks remove some_old_room@conference.example.net + +Delete the bookmark of a URL without requesting confirmation:: + + $ li bookmarks remove -t url https://unused_url.example.net + + +add +=== + +Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as +positional argument. If you are bookmarking an URL, you need to specify it with ``-t +url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it. + +For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``, +and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically +when you're connecting. + +If you're using add on a jid/URL which already exists, the metadata will be updated. + +examples +-------- + +Add a bookmark to Salut à Toi official chat room:: + + $ li bookmarks add sat@chat.jabberfr.org -a + +Add a link to Salut à Toi official website:: + + $ li bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel"
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/common_arguments.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,214 @@ +================ +common arguments +================ + +Some arguments are used in many commands. This page describe them. + +.. _libervia-cli_common_profile: + +profile +======= + +profile arguments are really common, they allow you to select your profile. +If you don't select any, the default profile is used, which is the first +profile created or the one you have explicitly set. You can check which profile +is used by default with ``li profile default``. + +The common arguments for profile are: + +``-p PROFILE, --profile PROFILE`` + to select the name of your profile. It can be a profile key like ``@DEFAULT@`` + +``-c, --connect`` + connect the profile to the XMPP server before doing anything else. If your + profile is already connected, nothing happen. This is specially useful in scripts. + +``--start-session`` + starts a session without connecting, this can be needed if you can't connect but + you need to access your session e.g. to change parameters. + This is advanced used and is not need in most common cases. + +``--pwd PASSWORD`` + the password of your profile, needed if the session is not started yet. + +.. note:: + + using the ``--pwd`` option is not secure if you are not the only user of your machine: + the password will appear **IN CLEAR** in the list of launched processes, or in the + history of your shell. If the profile password is needed and not specified, it will be + prompted (with echo disabled). If you are on a shared machine or if anybody can access + your shell history at some point, you should either connect first your profile with an + other frontend (Primitivus for instance), or avoid the ``--pwd`` option and use the + prompt instead. + +.. _pubsub_common: + +pubsub +====== + +pubsub arguments are used in many commands, they allow you to select a service, node and +items. Depending on the command, you may only not be able to select an item, or you may +select one or multiple items. + +The common arguments for pubsub are: + +``-u PUBSUB_URL, --pubsub-url PUBSUB_URL`` + retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an + ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to + retrieve the location of the XMPP node/item, if available. + Note that you can override parts of the location in the URL if you specify service, node + or item. + + e.g.:: + + $ li blog get -u https://www.goffi.org + +``-s SERVICE, --service`` + used to specifiy the JID of the pubsub service + +``-n NODE, --node NODE`` + used to specifiy the pubsub node + +``-i ITEM, --item ITEM`` + for commands where an item can be specified, you do it with this option. In some + commands, multiple items can be specified, in this case just use this arguments several + times. + +``-L, --last-item`` + when an item id is needed, you can use this option to retrieve the last published item. + e.g.:: + + $ li blog edit --last-item + +``-M, --max-items`` + use to specify a maxium number of items to retrieve, when it makes sense. + Note that this is using the pubsub max (i.e. defined in + `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should + implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in + this case the ``-m, --max`` argument should be prefered. See below for RSM common + arguments. + +result set management +===================== + +Result Set Management (RSM) common arguments are used to navigate into pages of results +when lot of elements may be expected. Given a result with a large number of arguments, a +*page* is set of elements which correspond to an *index* (a page number). For instance if +you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to +20 included. + + +``-a ITEM_ID, --after ITEM_ID`` + find page after this item. You usually use the last item id of the latest page you got. + +``-b ITEM_ID, --before ITEM_ID`` + find page before this item. This this usually used when you check items backwards + +``--index RSM_INDEX`` + index of the page to retrieve. Note that first page has index **0**. + +``-m RSM_MAX, --max RSM_MAX`` + used to specify a maxium number of items to retrieve per page. Note that the actual + maximum number of items per page used may be lower if the service used consider that + your request is too big. + +message archive management +========================== + +Message Archive Management (MAM) argument is used by some commands (related to instant message or +pubsub) to filter results. + +There is currently only one argument in this group: + +``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` + specify a MAM filter to use. Depending on the service supporting MAM, some filters can + be used to do things like full text search. The available filters depend on the service + you use, please check documentation of your service. + +order-by +======== + +Order-By argument specify how the returned elements are sorted. + +There is currently only one argument in this group: + +``-o {creation,modification}, --order-by {creation,modification}`` + specify how result is sorted. with ``creation``, first created element is returned + first. There is no notion of *creation* of *modification* in original + `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an + existing id will overwrite the older one, creating a new item. With this option, we use + the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and + *creation* time is the time when the first item has been published, before being + overwritten. + + In the case of ``modification``, if an item is overwritten, it reappears on top, this is + the default pubsub sorting order. + +progress +======== + +This single option may be used when a long operation is happening, like a file transfer. + +``-P, --progress`` + Show progress bar. + +verbose +======= + +``--verbose, -v`` + Add a verbosity level (can be used multiple times). Use to have more concise output by + default when it makes sense. + +.. _draft_common: + +draft +===== + +Common arguments used when an edition is potentially long to do, and a file may be kept +until publication. + + +``-D, --current`` + Used when you have started to edit something (e.g. a blog post), which is not yet + published, and you want to continue your work. + + e.g.:: + + $ li blog edit -D + +``-F DRAFT_PATH, --draft-path DRAFT_PATH`` + Used when you have started to edit something and want to continue your work from this + file. In other words, it's similar to ``-D, --current`` except that you specify the file + to use instead of using the last available draft. + +.. _libervia-cli_output: + +output +====== + +Output is used when you want to get the result of the command in a specific way. It may be +used, for instance, to retrieve the result formatted in JSON so the data can be easily +manipulated by a script, or if you want only a specific element of the result. + +``-O {…}, --output {…}`` + specifiy the output to use. Available options depends of the command you are using, + check ``li [your command] --help`` to know them. + + e.g.:: + + $ li blog get -O json + +``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` + depending of the output selected, you may have options to customise the output. + For instance, if you use the ``template`` output, you may use an option to display the + result in a browser. + + e.g.:: + + $ li blog + + Some options expect parameters, in this case they can be specified using ``=``. + + e.g. specifiying a template to use:: + + $ li blog get -O template --oo browser --oo template=/tmp/my_template.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/debug.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,93 @@ +===================================================== +debug: tools to help debugging/monitoring Salut à Toi +===================================================== + +``debug`` groups commands to monitor or manipulate SàT and XMPP stream. + +.. _libervia-cli_debug_bridge_method: + +bridge method +============= + +Call a method of the bridge. You have to provide the name of the method and the arguments +as positional arguments. Arguments are evaluated as Python code (using ``eval``), so you +need to properly escape them (for your shell **and** Python). You can either split your +Python arguments as many shell arguments, or put them in a single shell argument. + +You profile is automatically set if the method requires it (using the value of ``-p +PROFILE, --profile PROFILE``), so you must not specify it as an extra argument. + +You can refer to `Bridge API documentation`_ to get core methods signatures + +.. _Bridge API documentation: https://wiki.goffi.org/wiki/Bridge_API + + +examples +-------- + +Send a message using a single shell arguments for all Python arguments. We +use first the method name (``messageSend``), then the required arguments (see `Bridge +API documentation`_ for details), without the profile as it is automatically set. We +specify them as Python in one shell argument, so we use single quote (``\```)first for +s hell string, and inside it we use double quote (``"``) for Python strings:: + + $ li debug bridge method messageSend '"louise@example.org", {"": "test message"}, {}, "auto", {}' + +.. note:: + + This is for debugging only, if you want to send message with li, use :ref:`libervia-cli_message_send`. + +Get version string of SàT:: + + $ li debug bridge method getVersion + + +bridge signal +============= + +Send a fake signal. This is specially useful to test behaviour of a frontend when a +specific event happens. To use is you just need to specify the name of the signal and the +arguments to use (using Python eval in the same way as for libervia-cli_debug_bridge_method_). + +example +------- + +Send a note with ``info`` level and hand written XMLUI. Here me use a shell variable to +store the level, so we can easily change it if we want to use an other level for tests. +Note the use of quotes (to escape both for shell and Python):: + + $ LEVEL='info'; li debug bridge signal -c actionNew '{"xmlui": '"'"'<?xml version="1.0" ?><sat_xmlui title="test title" type="dialog"><dialog level="'$LEVEL'" type="note"><message>test message\non\nseveral\nlines</message></dialog></sat_xmlui>'"'"'}' '""' -1 + + +monitor +======= + +Show raw XML stream. By default, output is pretty formatted/highlighted and you get all +streams in both direction. You can filter the direction using ``-d {in,out,both}, +--direction {in,out,both}``. + +For this to work, you need to set the option ``Activate XML log`` in the ``Debug`` section +of your parameters. + +Verbosity is used, to print details on the direction of a stanza, use ``--verbose, -v`` + +example +------- + +Monitor raw XML stream:: + + $ li debug monitor -v + +theme +===== + +Show the colour constants in their respective colour, according to background (``light`` +or ``dark``). If backround option is not set in ``sat.conf``, it will be autodetected, and +colour theme will be modified accordingly. + +example +------- + +Show colours with the set background:: + + $ li debug theme
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/encryption.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,126 @@ +======================================== +encryption: encryption sessions handling +======================================== + +Salut à Toi being an XMPP client does encryption by default between client and server. In +addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the +payload of messages are encrypted to be hidden from the servers (and their +administrators). The ``encryption`` commands are here to handle those e2e encryption +sessions and algorithms. + +.. note:: + + For the moment, only one 2 one chat messages can be e2e encrypted + +algorithms +========== + +Display e2e encryption algorithms available in this instance of Salut à Toi. + +example +------- + +Show available e2e algorithms:: + + $ li encryption algorithms + +get +=== + +Display which encryption session is currently active with the given entity. + +The only required argument is the JID of the entity. + +If not e2e encryption session exist, a message will be displayed and li will exit with a +non zero code: this means that the messages are in clear in the XMPP servers, but normal +XMPP encryption is not affected (message should still be encrypted between client and +server and between servers). + +If an e2e encryption session exist, you'll see the algorithm name and its namespace. In +case of e2e encryption which only works from device to device (e.g. it's the case with +``OTR`` which doesn't support multiple devices), you'll also see the resources of the +devices where the encryption is active in ``directed_devices`` + +example +------- + +Check if session is encrypted with Louise:: + + $ li encryption get louise@example.org + +start +===== + +Start e2e session with an entity. + +You need to specify the JID of the entity you want to start a session with as a positional +argument. + +By default, SàT will select itself the algorithm to use among those available, but you can +specify one using either its name with ``-n NAME, --name NAME`` or its namespace using +``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo`` +while the namespace is the longer (e.g. ``urn:xmpp:otr:0``). + +If an encryption session is started but one with an other algorithm was already there, the +original session will be stopped and replaced by one with the new requested algorithm. You +can change this behaviour by using ``--encrypt-noreplace``: in this case the command will +fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e +encryption session was already started with an other algorithm), and return a non-zero +code. If an e2e encryption session was already started with the requested algorithm, the +command will succeed in all cases and nothing will be changed. + +examples +-------- + +Start e2e encryption with Pierre, using the algorithm selected by SàT:: + + $ li encryption start louise@example.net + +Start an OMEMO session with Louise:: + + $ li encryption start -n omemo louise@example.org + +stop +==== + +Terminate an e2e session with given entity. The entity must be specified as positional +argument. + +After this command is run, the messages with specified entity will not be e2e encrypted +anymore (but this won't affect encryption between SàT and XMPP server and between XMPP +servers). + +example +------- + +Stop the e2e encryption session with Pierre:: + + $ li encryption stop pierre@example.net + +trust ui +======== + +Run the user interface to handle trust with given entity and given algorithm. The user +interface depends on the algorithm used, but it generally shows you the fingerprints +associated with your contact or contact devices, and asks you if you trust them or not. + +The only mandatory argument is the jid of your contact. + +By default the currently active encryption session algorithm is used, but you may manage +trust for another algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE, +--namespace NAMESPACE``. + +.. note:: + + Trusting a contact or a device means that you certify that this contact or device is + the one you want to talk too. You should not trust a device if you have not verified by + an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the + fingerprint physically if possible (i.e. in front of your contact, not with computer + networks in the middle). + +example +------- + +Manage ``OMEMO`` trust with Louise devices:: + + $ li encryption trust ui -n omemo louise@example.org
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/event.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,81 @@ +======================== +event: events management +======================== + +Event commands allows you to create/modify or get data about an event, and to manage your +invitees. + +list +==== + +List events available on a service + +example +------- + +Retrieve events of profile:: + + $ li event list + +.. _libervia-cli_event_get: + +get +=== + +Get metadata about a specific event. + +example +------- + +Retrieve an event metadata:: + + $ li event get -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0' + +.. _libervia-cli_event_create: + +create +====== + +Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``, +and an id with ``-i ID, --id ID`` (default id is used if omitted). + +Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key +can be a custom data or one of: + +name + name of the event +description + details of the event +image + URL of the main picture of the event +background-image + URL of image to use as background +register + a boolean value, set to ``true`` if you want to register the event in your local list + +example +------- + +Create an event about to celebrate New Year:: + + $ li event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg + + +modify +====== + +This command in the same way as libervia-cli_event_create_ but modify an existing event. You need to +specify the node of the event to modify using ``-n NODE, --node NODE``. + +example +------- + +Add a background image to the New Year event created above:: + + $ li event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg + + +invitee +======= + +Subcommands to handle guests. Please check :ref:`libervia-cli_event_invitee`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/event_invitee.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,94 @@ +.. _libervia-cli_event_invitee: + +======================================== +event/invitee: event invitees management +======================================== + +``invitee`` groups commands to invite somebody to an event, get or set data about an invitee, and list all invitees. You can send an invitation by e-mail to people without XMPP account. + +.. _libervia-cli_event_invitee_get: + +get +=== + +Retrieve the RSVP status of one guest. Note that you must the invitees node and not the +event node. To retrieve invitees node, use :ref:`libervia-cli_event_get` with the event node. + +You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare +jid will be used). + +If no response is known yet, no data is returned. + +example +------- + +Get RSVP of Louise:: + + $ li event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org + + +.. _libervia-cli_event_invitee_set: + +set +=== + +Set your own RSVP data. Note that as for libervia-cli_event_invitee_get_ you must use +invitees node and not the event node. + +Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of +``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value +must be an integer. + +example +------- + +Indicate that you'll come to an event with 3 guests:: + + $ li event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3 + +list +==== + +Get and format the RSVP of your invitees. Note that as for libervia-cli_event_invitee_get_ and +libervia-cli_event_invitee_set_ you must use invitees node and not the event node. + +By default, only people who have answered are shown. You may use ``-m, --missing`` to show +other people which were invited, but have not answered yet. When using this option, you +can also use ``-R, --no-rsvp`` to only show people which have not answered yet. + +You'll also have a small summary indicating how many people who can expect at your event. + +example +------- + +Get the full list of invitees (including those who didn't answered yet) with the RSVP formatted:: + + $ li event invitee list -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -m + +invite +------ + +Invite somebody to an event. The invitation is done by e-mail, a guest account will be +created. Contrary to other ``invitee`` commands, in this one you'll use the event node +directly. + +This command is really similar to :ref:`libervia-cli_invitation_create` + +E-mail address is specified using ``-e EMAIL, --email EMAIL`` and you'll need to give an +URL template (using ``-U URL_TEMPLATE, --url-template URL_TEMPLATE``)leading to your +website page handling the invitation (for Libervia default invitation page is +``<your_server>/g/<uuid>``). You can use ``{uuid}`` as a placeholder which will be +replaced by event's id. + +You'll probably want to specify the name of the invitee, using ``-N NAME, --name NAME`` +and your own name (as the host inviting), using ``-H HOST_NAME, --host-name HOST_NAME``. +The language spoken by your guest can be specified using ``-l LANG, --lang LANG``, it is +mainly useful if you have many invitee speaking different languages. + +example +------- + +Pierre is inviting Louise (whose e-mail address is ``louise_email@example.net``) to an +event he's organising:: + + $ li event invitee invite -e louise_email@example.et -N "Louise" -H "Pierre" -l fr -U "https://www.example.org/g/{uuid}" -u "xmpp:pierre@example.org?;node=generic%2F61400ea7-a2a2-4ce0-9b68-3735b602f671"
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/file.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,173 @@ +======================================== +file: files sending/receiving/management +======================================== + +``file`` group all commands related to file management, and allows you to send easily a +file to a contact or device from the command line. + +send +==== + +Send a file to a contact. + +The file will be sent using best available method (which is Jingle File Transfer when +available), and will try to send the file in P2P when possible. If P2P is possible, the +signal is sent through the server (metadata, negotiation, etc.), while the file itself +goes directly from the source device to the target device. When P2P is not possible, the +file may go through the server or an other one (if a proxy is used for instance). + +When sending a file, you specify one or more file(s) to send, and the either the bare jid +or the full jid of the target device. If bare jid is specified, the main resource will be +used. + +You'll usually want to see the progression of the transfer, use ``-P, --progress`` for +that. + +If you send several files at once, you may want to use ``-b, --bz2`` to group them in a +single compressed ``tar.bz2`` archive (the client receiving the files will then receive a +single file, than the user can then decompress). + +By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to +specify another one. + +The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace +NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like +a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group +of files, for instance for a photo album). + +examples +-------- + +Send a file to Louise, with a progress bar:: + + $ li file send -P some_file.ext louise@example.org + +Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in +the ``/some/path`` path:: + + $ li file send -P -N holidays -d /some/path some_photo.jpg files.example.org + +.. _libervia-cli_file_request: + +request +======= + +Ask to get a file from a device/sharing service. A file is requested using one or more +metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H +HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo +HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N +NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific +and not (yet?) XMPP standards. + +If you already know the hash, it's the most efficient and recommended way to retrieve a +file. + +You need to specify the full jid of the device or the sharing service as a positional +argument. + +By default the file is downloaded in current directory, but you can specify an other one +(and an other filename) with ``-D DEST, --dest DEST``. + +If you want to see progression of the transfer, use ``-P, --progress``. + +examples +-------- + +Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service +``files.example.org``, with a progress bar:: + + $ li file request -P -d photos/demo_album -n some_file.jpg files.example.org + +Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't +specify it), and save it to file ``dest_file.txt``:: + + $ li file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org + +receive +======= + +Wait for a file (or several ones) to be received, and accept it if it match criteria. + +You should specify which jid you are expecting a file from, using the positional +arguments. If you don't, all files will be accepted, which can be dangerous if some +malicious user send you a file at this moment. + +To see progression (this is recommended), you can use the ``-P, --progress`` options. + +By default, if a file with the same name as the proposed one exists, the transfer will be +denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely +trust the sender in this case, as the name is chosen by her, and could be malicious, or it +could override an important file. + +If you expect several files, you can use the ``-m, --multiple``, in this case the command +won't stop after the file received file, and you'll have to manually stop it with +``Ctrl-C`` or by sending a ``SIGTERM``. + +File(s) will be written in the current directory, but you may specify an other destination +with ``--path DIR``. + +examples +-------- + +Accept and receive the next file, save it to local directory and show a progress bar:: + + $ li file receive --progress + +Several files are expected from Louise, accept them and store them do +``~/Downloads/Louise``:: + + $ li file receive --multiple --path ~/Downloads/Louise louise@example.org + +get +=== + +Download a file from an URI. This commands handle URI scheme common with XMPP, so in +addition to ``http`` and ``https``, you can use it with ``aesgcm`` scheme (encrypted files +with key in URL, this is notably used with OMEMO encryption). + +As usual, you can use ``-P, --progress`` to see a progress bar. + +example +------- + +Download an encrypted file with a progress bar, and save it to current working directory +with the same name as in the URL (``some_image.jpg``). The URL fragment part (after ``#``) +is used for decryption, so be sure to not leak the URL when you manipulate one:: + + $ li file get -P "aesgcm://upload.example.org/wvgSUlURU_UPspAv/some_image.jpg#7d8509c43479591f8d8492f84369875ca983db58f43225c40229eb06d05b2037c841b2346c9642a88ba4a91aa96a0e8f" + +upload +====== + +Upload a file to your XMPP server (or an other entity if specified). The upload will be +done using `XEP-0363 (HTTP File Upload)`_, and the public URL to retrieve the file will be +printed. Note that anybody knowing this URL can download the file you've uploaded. + +The path to the file to upload is expected as first argument, then optionally the entity +of the service to upload too (by default, this is autodetected if your server offers this +feature). + +As usual, you can use ``-P, --progress`` to see a progress bar. + +You can encrypt the file using ``AES GCM`` with the ``-e, --encrypt`` argument. You will +then get an ``aesgcm://`` link instead of the usual ``https``, this link contains the +decryption key (in the fragment part) so be sure to not leak it and to transmit it only +over encrypted communication channels. + +.. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload + +example +------- + +Upload a document to a server:: + + $ li file upload -P ~/Documents/something_interesting.odt + +Encrypt and upload a document to server:: + + $ li file upload -P -e ~/Documents/something_secret.odt + +share +===== + +Subcommands for advanced file sharing. Please check :ref:`libervia-cli_file_share`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/file_share.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,108 @@ +.. _libervia-cli_file_share: + +================================== +file/share: advanced files sharing +================================== + +``share`` groups commands for listing file available on a device/service, sharing a file +or directory, and inviting people to retrieve files. + +.. _libervia-cli_file_share_list: + +list +==== + +List files available on a device or sharing service. You mainly have to specify the jid of +the device/service where the files are stored (if jid is omitted, your own jid will be +used, so you can check what you are sharing). + +.. note:: + + you have to use the full jid of the device if you want to list files available on a + device. + +You may specify a path using ``-d PATH, --path PATH``. + +File and directories are printed with a different colour if you use default output. + +examples +-------- + +List files shared from a device (note that we use a full jid here):: + + $ li file share list louise@example.org/some_resource + +List files available on a sharing service at the path ``/photos``:: + + $ li file share list -d photos files.example.org + +Louise wants to list the file shared by Pierre:: + + $ li file share list pierre@files.example.org + +path +==== + +Share a local file or directory with a list of entities, or publicly. The files can then +be listed or requested using libervia-cli_file_share_list_ or :ref:`libervia-cli_file_request`. + +You specify the file or directory the positional ``path`` argument. By default the name of +the file/directory is used, but you can give a different one using ``-n NAME, --name +NAME``. + +You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many +time as necessary. If you don't specify any entity, the file will only be accessible by +your own devices. If you want to make your file accessible to everybody, use ``--public`` +(note that this means that your file is accessible to the world, i.e. also to people you +don't know, so use this option carefully). + +examples +-------- + +Share the file ``interesting_doc.odt`` with Pierre and Louise:: + + $ li file share path -j pierre@example.net -j louise@example.org interesting_doc.odt + +Imagine that you have built a weather station and want to make its data public. You can +share the directory ``~/weather_station_data`` with the world, using the name ``public +weather data``:: + + $ li file share path --public --name "public weather data" ~/weather_station_data + +invite +====== + +This command send an invitation for a file sharing repository to an XMPP entity. + +The invitation is a non standard (yet?) way to notify somebody of the existence of a files +repository. + +Beside the positional arguments ``service`` and ``jid``, which are respectively the +service where is the files repository and the jid of the entity to invite, you mainly have +to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and +``N NAMESPACE, --namespace NAMESPACE``. + +Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a +generic files repository or a photo album. + +Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL, +--thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of +the album in e.g. Libervia. + +example +------- + +Pierre wants to invite Louise to view his ``summer holidays`` photo album:: + + $ li file share invite -P "photos/summer holidays" -t photos pierre@files.example.net + louise@example.org + +affiliations +============ + +subcommands for file sharing affiliations management. please check :ref:`libervia-cli_file_share_affiliations`. + +configuration +============= + +subcommands for retrieving/modifying file sharing node configuration. please check :ref:`libervia-cli_file_share_configuration`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/file_share_affiliations.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,56 @@ +.. _libervia-cli_file_share_affiliations: + +============================================================= +file/share/affiliations: file sharing affiliations management +============================================================= + +``affiliations`` let you manage access permission to your shared files repository, in a +way similar as for pubsub. + +Affiliations with file sharing are not standard and will only work with the SàT file +sharing component. + +Affiliations are similar to pubsub ones: + +``owner`` + Has full permissions on the node, including changing affiliations. Owner can't be + changed at the moment. + +``publisher`` + Can read, upload and delete files + +``member`` + Can access file but can't modify them or add new ones + +``none`` + Is not a member of this node, use it to remove an existing affiliation. + + +get +=== + +Retrieve entities affiliated to this file sharing node, and their role + +example +------- + +Get affiliations of a file sharing node:: + + $ li file share affiliations get -P "/some/path" louise@files.example.org + +set +=== + +Set affiliations of an entity to a file sharing node. + +examples +-------- + +Allow read access to a photo album to Louise:: + + $ li file share affiliations set -c files.example.net -P "/albums/holidays" -a louise@tazar2.int member + +Remove access to a directory from an old address of Pierre, and give it to the new one:: + + $ li file share affiliations set -c files.example.net -N "some_namespace" -P + "/interesting/directory" -a pierre@example.com none -a pierre@example.org member
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/file_share_configuration.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,38 @@ +.. _libervia-cli_file_share_configuration: + +========================================================= +file/share/configuration: file sharing node configuration +========================================================= + +``configuration`` commands are use to check or modify settings of a file sharing node. +This is not standard and specific to SàT file sharing component. + +The configuration is similar as pubsub one. + +Only ``access_model`` can be used so far, with the ``open`` or ``whitelist`` values. + + +get +=== + +Retrieve file sharing node configuration. + +example +------- + +Get configuration of a file sharing node:: + + $ li file share configuration get -P "/some/path" louise@files.example.org + +set +=== + +Set configuration of a file sharing node. + +example +------- + +Make a repository public:: + + $ li file share configuration set -c files.example.net -P "/public_files" -f + access_model open
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/forums.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,102 @@ +============================== +forums: forums topics handling +============================== + +Forums are internally a way to organise blog nodes open to many publishers. The ``forums`` +commands let you manage the structure of topics. You may have several different structures +in one PubSub forums node, this can be useful if you have multi-lingual forums. + +.. _libervia-cli_forums_get: + +get +=== + +Get and print the structure of forums. Beside the classic PubSub node arguments, you may +specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have +several structures of forums, for instance one per language. + +If you use the default output, the verbosity is used to retrieve details of topics. + +examples +-------- + +Get structure of default forum with details:: + + $ li forums get -v + +Get structure of French forums in JSON:: + + $ li forums get -k fr -O json + + +edit +==== + +Edit the structure of XMPP forums. As for libervia-cli_forums_get_ you may specify the key beside +the classic PubSub node arguments. The edition works the same as for :ref:`libervia-cli_blog_edit`. + +To edit the structure you'll get a JSON file which is a list of object where the topic +metadata are set. You can use the following metadata: + +``main-language`` + a language code, using `ISO 639`_ +``name`` + short name of the forum +``title`` + title of the topic/category in the given language +``short-desc`` + small description of the topic/category +``desc`` + long description of the topic/category +``uri`` + URI to the PubSub node containing the messages of the topic (it's actually a blog node + with suitable permissions). URI must only be set for topic, not for categories. +``sub-forums`` + list of object with the same metadata (i.e. other topics or categories) + +Here is a small example of a forum structure: + +.. sourcecode:: json + + [ + { + "main-language": "en", + "name": "short-name", + "title": "This is a category", + "short-desc": "short description about the category", + "desc": "this is a an example of a long description" + "sub-forums": [ + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "some intereting topic", + "short-desc": "This is a description explaining what the topic is about" + }, + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "a second topic", + "short-desc": "This topic is about bla bla bla" + }, + ], + }, + { + "main-language": "en", + "title": "An other category", + "sub-forums": [ + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "yet another topic", + "short-desc": "This is a demo topic, made for an example" + }, + ] + } + ] + + +.. _ISO 639: https://www.iso.org/iso-639-language-codes.html + +example +------- + +Edit structure of forums on a PubSub service:: + + $ li forums edit -s pubsub.example.org
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/identity.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,36 @@ +============================= +identity: identity management +============================= + +Identity use several XMPP extensions (like vcards) to retrieve or set informations about +an entity. For now it's really basic and only nickname and avatar are managed. + +get +=== + +Retrieve informations about the identity behind an XMPP entity. You only have to specify +the jid of the entity, and you'll get (if set) his/her/its nickname and data about the +avatar. + +When available, cached values are returned by defaut. If you want to ignore the cache, use +the ``--no-cache`` option (of course this can result in more network requests). + +example +-------- + +Get identity information about an entity:: + + $ li identity get somebody@example.org + +set +=== + +Set identity data to the server, using various XMPP extensions. So far, you can only +change the nickname of an entity using ``-n, --nick`` or or more times + +example +------- + +Set 2 nicknames for default profile:: + + $ li identity set -n toto -n titi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/index.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,94 @@ +.. _libervia-cli_documentation: + +============ +Libervia CLI +============ + +Libervia CLI is the Command Line Interface of Libervia + +``libervia-cli`` is the command to launch it. + +``li`` is short alias for ``libervia-cli``, it is the command used through this +documentation. + +Overview +======== + +``li`` is a powerful tool to work with Salut à Toi/XMPP. +With it you can send chat messages, share files, retrieve avatars, write blog entries, etc. + +Usage +===== + +To get help on commands or their options, use:: + + $ li --help + +which can be used on any command, so if you need help on ``message send`` command, just do:: + + $ li message send --help + +With li, you always enter commands first, then options and arguments. + +There are several levels of commands: first one is the main category (``message``, +``blog``, ``avatar``, etc.), then there are often subcommands (e.g. ``message send``). + +After the commands come the options. For instance if you want to send a message, you can +get the available options with ``--help`` as explained above:: + + $ li message send --help + usage: li message send [-h] [-p PROFILE] [--pwd PASSWORD] [-c] [-l LANG] [-s] + [-n] [-S SUBJECT] [-L SUBJECT_LANG] + [-t {chat,error,groupchat,headline,normal,auto}] + [-e ALGORITHM] [--encrypt-noreplace] [-x | -r] + jid + + positional arguments: + jid the destination jid + + optional arguments: + -h, --help show this help message and exit + -p PROFILE, --profile PROFILE + Use PROFILE profile key (default: @DEFAULT@) + --pwd PASSWORD Password used to connect profile, if necessary + -c, --connect Connect the profile before doing anything else + -l LANG, --lang LANG language of the message + -s, --separate separate xmpp messages: send one message per line + instead of one message alone. + -n, --new-line add a new line at the beginning of the input (usefull + for ascii art ;)) + -S SUBJECT, --subject SUBJECT + subject of the message + -L SUBJECT_LANG, --subject_lang SUBJECT_LANG + language of subject + -t {chat,error,groupchat,headline,normal,auto}, --type {chat,error,groupchat,headline,normal,auto} + type of the message + -e ALGORITHM, --encrypt ALGORITHM + encrypt message using given algorithm + --encrypt-noreplace don't replace encryption algorithm if an other one is + already used + -x, --xhtml XHTML body + +If you want to send a message to, say, ``pierre@example.net``, and encrypt it with OMEMO, +just do the following:: + + echo "hi, I'm writing with li" | li message send -e omemo pierre@example.net + +(note that with OMEMO, you need to have previously validated fingerprint of your contact +for this to work). + +The different commands are explained in dedicated sections. + +.. toctree:: + :caption: li commands: + :glob: + :maxdepth: 2 + + common_arguments + * + + +Tutorial +======== + +You can check this third party tutorial: https://blog.agayon.be/sat_jp.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/info.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,77 @@ + +================================== +info: retrieve various information +================================== + +``info`` groups subcommands used to retrieve read-only informations. + +disco +===== + +Display discovery information (see `XEP-0030`_ for details). This can be used to check +which features you server or a service is offering, and which items are available (items +can be services like chat room, gateways, etc). + +You only have to specify the jid of the entity to check, and optionally a node. + +By default both infos and items are requested, but you can restrict what to request by +using ``-t {infos,items,both}, --type {infos,items,both}`` + +.. _XEP-0030: https://xmpp.org/extensions/xep-0030.html + + +example +------- + +Request infos and items from a server:: + + $ li info disco example.org + +version +======= + +Request software version of an entity. You only need to specify the jid of the entity as +positional argument. + +Depending of the software and its configuration, you have software version, software name, +and the operating system on which the software is running. + +example +------- + +Check version of a server:: + + $ li info version example.org + +session +------- + +Give information about the session of the given profile. You'll get the full jid currently +used on the server, and the time when the session was started (which may not be the same +time as when the connection with the XMPP server was started). + +example +------- + +Get session informations:: + + $ li info session + +devices +------- + +List known devices for an entity. You'll get resource name, and data such as presence +data, and identities (i.e. name and type of the client used). + +If entity's bare jid is not specified, a list of your own devices is returned. + +example +------- + +List known devices of Louise:: + + $ li info devices louise@example.org + +Check if we have other devices connected:: + + $ li info devices
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/input.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,119 @@ +================================================ +input: automatise commands using external inputs +================================================ + +``input`` is a way to use external data (like file in a specific format) as input +arguments. It may be seen as a something similar to ``--output`` but for inputs. + + +csv +=== + +CSV (for Comma-Separated Values) is a common format for tabular data. It is widely used in +spreadsheet software (at least at en export format). With ``csv`` command, you can use +columns a CSV file as arguments to li commands. + +To set the command, you'll write in sequence what to do with each column of your data. +For each column you can: + +- specify a short option name using ``-s ARGUMENTS, --short ARGUMENTS`` (short options are + the ones with a single ``-``) +- specify a long option name using ``-l ARGUMENTS, --long ARGUMENTS`` (long options are + the ones with two ``-``) +- specify a positional argument using ``-p ARGUMENTS, --positional ARGUMENTS`` +- indicate to use the column data with ``stdin`` using ``-i, --stdin`` +- ignore the column if it's not used in the li command, using ``-x, --ignore`` + +After each column specification, you may use a filter to manage the value. So far the +following filters are available: + +``-S, --split`` + This will split the value (on any whitespace character, discarding empty values) and + repeat the option which each item. This is useful when you are using an option which can + be repeated (like ``-t TAG, --tag TAG`` with ``li blog set``). + +``-E ARGUMENTS, --empty ARGUMENTS`` + Indicate what to do if the column value is empty (by default en empty string is used). + You can use either ``skip`` to skip the whole row, or ``ignore`` so the option will not + be set at all (which is different from the default which will still set the option but + with an empty string). + +CSV file is read from stdin, and by default unicode is expected. You may force an encoding +by using ``--encoding ENCODING``. + +By default all the rows are read, but you may want to ignore first rows (if they are used +for columns title, or if you have already handled part of the list). To do that, use the +``-r ROW, --row ROW`` option. + +When you test your command, it is better to do a dry run to see what will happen. The +``-D, --debug`` option is here for that: if you set it, the commands won't be actually +run, but the exact command which would be executed will be printed on screen. You should +always use this option first until you're sure that what you want will be executed. + +You may add verbosity level to help debugging. With a verbosity level of 2 (i.e. ``-vv``) +the value read from CSV will be printed. + +By default stdout and stderr of each launched command is ignored, but you can log them to +files using respectively ``--log LOG`` and ``--log-err LOG_ERR`` where ``LOG`` and +``LOG_ERR`` are paths to a log file to create. + +Once all the sequence and options are set, you write the li command that you want to use, +with all the needed static option (i.e. options which must be used each time). + + +example +------- + +Louise as a spreadsheet with a table like this: + +============================ ============ ============= =============== +title body internal data tags +============================ ============ ============= =============== +Some title a body ABC li demo +Something else another body XYZ li demo +Third one third body VWZ special_tag li +This one doesn't have a body 123 li demo numbers +last one last body 456 li demo numbers +============================ ============ ============= =============== + +She wants to use it as input data to create blog posts. + +She first saves the file using CSV format, let's say to ``~/blog_input.csv``. + +Then she checks ``li blog set --help`` to get name of options to use. She'll need to use +``--title`` for title, ``stdin`` for the body and ``-t`` for tags. Louise wants to +activate comments, so she also wants to use ``-C`` for all posts, and a tag to says it's +coming from the spreadsheet (using ``-t spreadsheet``) . + +The first row of the table is used for columns headers, so she'll start at row 1 with ``-r +1``. + +There is one row without body, Louise want to skip any row without body so she'll use the +``-E skip`` filter, just after specifying the body row. + +Reading column by column, the sequence is like this: + +``-l title`` + a title which goes to the ``--title`` long option of ``li blog`` +``-i -E skip`` + a body which goes to the stdin of ``li blog``. If the body is empty, the ``-E skip`` + filter tells to skip the whole row. +``-x`` + the ``internal data`` column is not used, so it is ignored +``-s t -S`` + the last column are the tags, so the ``-t`` short option is used. There are several of + them separated by spaces, so the ``-S`` filter is used to split the values. + +First she'll use the ``-D, --debug`` to check that the commands which will be executed are +the expected one:: + + $ li input csv -D -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv + +Everything seems fine, so she'll actually launch the command by running the same command +line but without the ``-D`` option:: + + $ li input csv -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv + +She could also have used ``--log`` and ``--log-err`` to check the logs of each command:: + + $ li input csv -r 1 -l title -i -E skip -x -s t -S --log /tmp/jp_blog_stdout.log --log-err /tmp/jp_blog_stderr.log blog set -C -t spreadsheet < ~/blog_input.csv
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/invitation.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,109 @@ +============================================== +invitation: invite people without XMPP account +============================================== + +Invitations allows you to invite people without XMPP account, so they can participate e.g. +to a discussion by using a specially generated link. This is a Salut à Toi specific +feature and those commands are rather low lever. + +.. _libervia-cli_invitation_create: + +create +====== + +Invite somebody to participate. This will create a guest account and a link with an +identifier to access this account, and send an invitation to the given email. + +The email is specified using ``-e EMAIL, --email EMAIL``, which can be used multiple times +to send the invitation to more than one address. + +You'll usually want to specify the name of the person you're inviting, using ``-n NAME, +--name NAME``, it may later be used in email sent or in the web page where your guest will +land. + +``-N HOST_NAME, --host-name HOST_NAME`` is used to specify the name of yourself (i.e. the +person which is inviting), it may be used in invitation message. + +You'll most of time have to specify the URL template using ``-u URL, --url URL``. This +will be used in the invitation email to construct the URL where your invitee will click. +You may use the string ``{{uuid}}`` in this template which will be replaced by the id +associated to the invitation. With Libervia, default invitation page is +``<your_server>/g/<uuid>``. + +The language of your guest can be specified using ``-l LANG, --lang LANG``, this is +notably useful if you have multilingual blog posts (e.g. for an event where people +speaking different languages are invited). + +The ``-x KEY VALUE, --extra KEY VALUE`` is used for extra data which depend on what you +are inviting your guests for. + + +example +------- + +Invite Louise, which is speaking French, to an event. The invitation is sent to her email +address ``louise_email@example.net``, is sent by Piotr, and must link to the Libervia +instance at ``https://www.example.org/g/<id>``. We use here the ``event_uri`` extra key:: + + $ li invitation create -n Louise -N Pierre -e louise_email@example.net -l fr -u "https://www.example.org/g/{uuid}" -x event_uri xmpp:pierre@example.org?;node=MnXe4ic2X8RUz6JAJuw4f9;item=org.salut-a-toi.event%3A0 + + +get +=== + +Get metadata for one specific invitation. You only have to specify the invitation id, and +you may use the option ``-j, --with-jid`` to also get the jid used for the invitation +(this will start the session of the invitee). + +example +------- + +Get invitation data for invitation with id ``okFec4gDz75My7iQAVTmsc``:: + + $ li invitation get okFec4gDz75My7iQAVTmsc -j + + +modify +====== + +This work the same way as libervia-cli_invitation_create_, you only have to specify the ``id`` of the +invitation. + +If you use the ``--replace`` argument, all the invitation data will be replaced by the +ones you're specifying. + +example +------- + +Change the language of the invitee for the invitation ``okFec4gDz75My7iQAVTmsc`` for +Slovak:: + + $ li invitation modify -l sk okFec4gDz75My7iQAVTmsc + + +delete +====== + +Delete XMPP account created for an invitation and invitation data + +example +------- + +Delete invitation with id ``okFec4gDz75My7iQAVTmsc``:: + + $ li invitation delete okFec4gDz75My7iQAVTmsc + + +list +==== + +List registered invitations. You may filter by the profile who made the invitation using +``-p PROFILE, --profile PROFILE``. +The invitations are shown by default using id as main data, and metadata below. + +example +------- + +List invitations:: + + $ li invitation list
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/merge-request.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,81 @@ +=============================================== +merge-request: create and manage merge requests +=============================================== + +Merge-request are used to propose some modifications to a project. They are generic and +are made to be used with several backends, but only Mercurial is implemented so far. + +To prepare a merge request with Mercurial, you just need to have a clone of the project, +and do your modifications (either directly, or in a bookmark, a branch, or a MQ patch). + +set +=== + +Create and publish a merge request. Once the modification on the project are done, simply +run the command from the repository (or specify its path with ``-r PATH, --repository +PATH``). If the project has set metadata (it can be done with a magic string in README), +you don't have to specify any service or node, it will be set automatically (but you still +can specify them if needed). + +You may associate one or more labels to your request using ``-l LABELS, --label LABELS``. + +By default, a confirmation is requested before publishing the request, you can publish +without confirmation by using the ``-f, --force`` flag. + +If you have already done a merge request and you just want to update it, check its id and +specify it with ``-i ITEM, --item ITEM``, this will override the previous request with the +new updated one. + +examples +-------- + +Publish a merge request (to be executed from the repository of the project you have +modified):: + + $ li merge-request set + +Update an existing merge request, which has the id ``123`` (to be executed from the +reposiroty of the project you have modified):: + + $ li merge-request set -i 123 + +Do a merge request for repository at path ``~/some_project``, specifying a label +indicating it's work in progress (WIP):: + + $ li merge-request set -r ~/some_project --label WIP + + +get +=== + +Get and print one or more merge requests. By default only some metadata are shown (without +the patches), but you can use ``--verbose, -v`` to show details. + +examples +-------- + +Show some metadata of last 5 merge requests:: + + $ li merge-request get -M 5 + +Display details for merge request with id 456:: + + $ li merge-request get -v -i 456 + + +import +====== + +Import a merge request into your project. You mainly have to be in the project repository +(or specify it using ``-r PATH, --repository PATH``) and to specify the id of the patch to +import (using ``-i ITEM, --item ITEM``). The behaviour depends of the type of the patch, +for Mercurial, the patch will be imported as `MQ`_ patch. + +.. _MQ: https://www.mercurial-scm.org/wiki/MqExtension + +example +------- + +Import the merge request with id 321:: + + $ li merge-request import -i 321
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/message.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,59 @@ +.. highlight:: sh + +================================ +message: chat message management +================================ + +Message commands let you send chat messages or manage your server message archives. + +.. _libervia-cli_message_send: + +send +==== + +Send a message to a contact or a chat room. +``stdin`` is used as message source. +You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed. +You can manage your encrypted session using ``encryption`` command. + +examples +-------- + +Send a message to a contact:: + + $ echo 'Salut à Toi!' | li message send louise@example.net + +Send a message encrypted with OMEMO:: + + $ echo 'pssst, this message is encrypted' | li message send -e omemo louise@example.net + +.. note:: + + Fingerprints of your destinee must have been accepted before using OMEMO, else message can't be encrypted + +Send a ``normal`` message marked as French with a subject:: + + $ echo 'Bonjour, je vous écris avec « Salut à Toi »' | li message send -l fr -t normal -S 'Ceci est un message de test' + +mam +=== + +Query archives using MAM. +This command allows you to check message archive kept on the server (i.e. not the local copy). +You usually want to specify a starting point, and a number of message to retrieve. If too many messages +are available, you'll have to use RSM commands to navigate through the results. + +examples +-------- + +Retrieve messages from last 2 days:: + + $ li message mam -S "2 days ago" + +Retrieve messages from last 5 hours on SàT official chat room:: + + $ li message mam -S "5 hours ago" -s sat@chat.jabberfr.org + +Retrieve 2 first messages of 2019 on SàT official chat room:: + + $ li message mam -S 2019-01-01 -s sat@chat.jabberfr.org -m 2
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/param.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,124 @@ +============================ +param: manage SàT parameters +============================ + +``param`` commands allows to retrieve or set parameters as well as to export/import them +to a XML file. + +Parameters are retrieve using a ``category`` and a ``name``, they are both case sensitive. + +``category`` is the name of the tabs that you see when you set parameters in a frontend +like Cagou or Libervia. + +.. note:: + + You need to have your session started to retrieve of modify parameters. If you can't + or are not willing to connect for any reason (e.g. no internet connection), you can + use the ``--start-session`` option to start the profile session without connecting it + to the XMPP server. + +get +=== + +Retrieve list of categories, parameters or a specific parameter value: + +- without argument, you'll get the list of categories +- with only a category specified, you'll get a list of parameters and their values +- with a category and a name, you'll get the value or requested attribute of the specified + parameters + +By default you'll get the value of the parameters, but you can request an other attribute +(for instance its ``type`` or ``constraint``) using the ``-a ATTRIBUTE, --attribute +ATTRIBUTE`` argument. + +You can set a security limit to retrieve only parameters allowed with this limit. +Security limit is an integer used in some frontends (like Libervia), to restrict +parameters modifiable by non privileged users. You can set it using ``--security-limit +SECURITY_LIMIT``, by default it is disabled (i.e. all parameters are returned). + +examples +-------- + +Get list of categories:: + + $ li param get + +Get list of parameters in ``General`` category:: + + $ li param get General + +Get JID set for default profile. It is set in ``Connection`` category, with the parameters +named ``JabberID`` (be careful with the case):: + + $ li param get Connection JabberID + +Get the type of the ``check_certificate`` parameters in ``Connection`` category:: + + $ li param get Connection check_certificate -a type + +Get the constraint of the ``Priority`` parameters in ``Connection`` category:: + + $ li param get Connection Priority -a constraint + +set +=== + +As expected, this command set a SàT parameter. The ``category``, ``name`` and ``value`` +are needed as positional arguments. + +``--security-limit SECURITY_LIMIT`` can be used if you want an update to be rejected if +the parameter is not modifiable with this limit. This can be useful if you use ``li`` from +an external tool and you want to limit damage risks, or for testing purpose. + +examples +-------- + +Use Markdown_ syntax for composition (e.g. for editing blog posts):: + + $ li param set Composition Syntax markdown + +Try to change jid of the profile with a low security limit, this command should fail:: + + $ li param set --security-limit 0 Connection JabberID some_random_jid@example.org + +.. _Markdown: https://daringfireball.net/projects/markdown/ + +.. _libervia-cli_param_save: + +save +==== + +Save the parameters structure to an external files. The parameters are saved as XML. The only +expected argument is the path to the destination file. + +.. note:: + + it's the parameters structure and not the parameters values which are saved. This is + low level method and most end users won't probably need it + +example +------- + +Save parameters structure to ``~/parameters.xml``:: + + $ li param save ~/parameters.xml + +.. _libervia-cli_param_load: + +load +==== + +Load and merge the parameters structure from external XML files. The only expected +argument is the path to the source file. + +.. note:: + + it's the parameters structure and not the parameters values which is loaded and merged. + This is low level method and most end users won't probably need it + +example +------- + +Load and merge parameters structure from ``~/parameters.xml``:: + + $ li param load ~/parameters.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/ping.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,20 @@ +========================================= +ping: get response time of an XMPP entity +========================================= + +``ping`` is more or less the equivalent of the command of the same name on most OSes, but +for XMPP. It send a `XEP-0199`_ PING and wait for the answer. When (and if) received, the +time to receive the answer is shown, else the time to receive the error message is shown. +This can be helpful to quickly test the connection with the server or a device. + +If you need to get only the response time (without text around), you may use ``-d, +--delay-only``. + +.. _XEP-0199: https://xmpp.org/extensions/xep-0199.html + +example +------- + +Get reponse time of a server:: + + $ li ping example.org
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pipe.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,43 @@ +================================================== +pipe: send/receive data stream through shell pipes +================================================== + +``pipe`` commands allow you to send or receive data stream through a Unix shell pipe. +Salut à Toi will create a network connection (using XMPP and Jingle) between you an your +contact. + +in +== + +Receive data stream. Data will be send to stdout, so it can be piped out or simply print +to the screen. You can specify bare jids of entities to accept stream for, by default all +streams are accepted. + +example +------- + +Receive a video stream, and redirect it to mpv_ so show the video:: + + $ li pipe in | mpv - + +.. _mpv: https://mpv.io/ + +out +=== + +Send data stream. Data comes from stdin, so you may use pipe in something or just write +some text. + +The only expected argument is the full jid of the device where the stream must be piped +out. + +example +------- + +Send a video to louise:: + + $ li pipe out louise@example.org/sat < some_video.webm + +Send output from ``cal`` command to louise:: + + $ cal | li pipe out louise@example.org/sat
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/profile.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,194 @@ +============================= +profile: SàT profile handling +============================= + +Profiles are the names associated with accounts in SàT, for more informations you can +check :ref:`glossary`. The `profile` commands help you create/delete/modify and manage +profiles. + + +connect +======= + +Unsurprisingly this command connects your profile, i.e. log-in your XMPP account. This +command uses :ref:`libervia-cli_common_profile` common commands, so you can use either ``-c, +--connect`` to connect to XMPP server, or ``--start-session`` if you want to start SàT +profile session without connecting to XMPP server (for instance if you want to modify +parameters without connecting to XMPP server). + +Note that :ref:`libervia-cli_common_profile` common commands are available in commands needing a +connected profile, ``li profile connect`` is interesting if you only want to connect your +profile/start a session. + +example +------- + +Connect the default profile:: + + $ li profile connect -c + + +disconnect +========== + +Disconnect your profile from XMPP server. There is no option beside the +:ref:`libervia-cli_common_profile` common options. + +example +------- + +Disconnect the profile ``pierre``:: + + $ li profile disconnect -p pierre + + +create +====== + +Create a new SàT profile. The only mandatory argument is the profile name, but you'll +probably want to associate an XMPP jid with ``-j JID, --jid JID`` and a profile password +with ``-p PASSWORD, --password PASSWORD``. By default, profile password will be used for +XMPP password (see note below), but you may specify XMPP password with ``-x PASSWORD, +--xmpp-password PASSWORD``. + +SàT is also capable to manage components, which can be seen as XMPP server independent +plugins. To create a component profile, you'll have to use ``-C COMPONENT, --component +COMPONENT`` where ``COMPONENT`` is the component entry point (check the documentation of +the component that you want to use to get its entry point). + +If you want a profile to connect automatically on backend startup (notably useful for +components), you can use the ``-A [{true,false}], --autoconnect [{true,false}]`` argument. + +.. note:: + + profile password and XMPP password are not the same: the profile password is the + password of your SàT profile, while the XMPP password is the one checked by your XMPP + server. If specify a jid with ``--jid`` and you don't specify an XMPP password, the + profile password will be used by default. + + The reason to have distinct password is that you may use a different password for + profile, including an empty one if you want SàT to connect your profile without + having to enter a password. Also the XMPP password is encrypted in database using the + profile password (which is not stored in database, only a hash is kept). + + +.. note:: + + passwords in li are currently specified directly on the command-line and not prompted, + this is not safe from a security point of view as people can see it on the screen, it + may stay in your shell history, or visible on process list. Keep that in mind if you're + in a public environment or on a public machine. This will be improved for SàT 0.8. + +examples +-------- + +Nestor wants to create a profile for its account on ``example.org``, he specifies a +profile password only, so it will also be used as the XMPP password:: + + $ li profile create nestor -j nestor@example.org -p some_password + +Create a component profile for the file sharing component (whose entry point is +``file_sharing``). The jid of the service is specified with ``--jid`` (note that we don't +use a node as it is a jid of a component) and the ``--xmpp-password`` is the shared +secret. Here the profile password is kept empty to not have to enter manually the XMPP +password each time we connect the service:: + + $ li profile create file_sharing -j files.example.org -p "" --xmpp-password + some_shared_secret -C file_sharing + + +default +======= + +This command simply prints the default profile (i.e. the profile used when none is +specified with ``-p PROFILE, --profile PROFILE``). The default profile is either the first +one that you've created, or the one you have explicitly set as default. + +example +------- + +Print default profile:: + + $ li profile default + + +delete +====== + +Delete a profile and all its associated data. This delete the SàT profile and associated +data (i.e. local data), but doesn't request the XMPP server to delete anything. + +By default a confirmation is requested, use ``-f, --force`` to avoid it (be cautious with +this option). + +example +------- + +Delete the profile of Pierre:: + + $ li profile delete pierre + + +info +==== + +Display information on a profile. For now, only the registered jid is shown, and +optionally the XMPP password. To display the XMPP password, use ``--show-password`` but be +careful that nobody can see your screen, as **this password will be shown in clear text**. + +example +------- + +Show jid and XMPP password for default profile:: + + $ li profile info --show-password + + +list +==== + +Show all profiles. You can use ``-c, --clients`` to show only client profiles, and ``-C, +--components`` to show only component profiles. + +example +------- + +Show all profiles:: + + $ li profile list + + +modify +====== + +Update an existing profile. You can use this command to change profile password (with ``-w +PASSWORD, --password PASSWORD``) or even disable it (with ``--disable-password``, this is +equivalent to using an empty profile password ; be cautious with this option, see the note +below). + +With ``-j JID, --jid JID`` and ``-x PASSWORD, --xmpp-password PASSWORD`` you can change +XMPP jid and password. + +This command can also be used to select the default password, use the ``-D, --default`` +flag for that. + +.. note:: + + Be cautious with ``--disable-password`` that means that no password will be needed with + any frontend of SàT to use this profile, and that XMPP password will be easy to + retrieve for anybody having an access to the machine where SàT is installed + +examples +-------- + +Pierre has changed server, he can update his jid and password like this:: + + $ li profile modify -p pierre -j pierre@example.org -x new_password + +Use ``louise`` as default profile:: + + $ li profile modify -p louise -D + +Disable profile password for default profile (be cautious, see the note above):: + + $ li profile modify --disable-password
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,361 @@ +.. _libervia-cli_pubsub: + +========================= +pubsub: PubSub management +========================= + +PubSub commands are low level command to handle a PubSub Service. +They are using the generic pubsub arguments + +For most of those commands, :ref:`pubsub_common` commands are used to specify the +destination item. + +set +=== + +Publish a pubsub item. + +``stdin`` is used to get the raw XML of the payload of the item to publish. + +``-f KEY VALUE, --field KEY VALUE`` can be used to specify publish options, i.e. option +which must be set if the node already exists, or used if the node is to be created, see +`XEP-0060 §7.1.5`_ for details. + +In the same way as for :ref:`libervia-cli_pubsub_node_create`, ``-F, --full-prefix`` can be used if +you need to specify the full option name. + +.. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options + +example +------- + +Create an item with a custom note XML:: + + $ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | li pubsub set -n "notes" + +get +=== + +Retrieve items from specified node. Default output is prettified and highlighted XML. + +example +------- + +Retrieve the last 5 notes from our custom notes node:: + + $ li pubsub get -n notes -m 5 + +delete +====== + +Delete an item from a node. If ``-N, --notify`` is specified, subscribers will be notified +of the item retraction. + +By default a confirmation is requested before deletion is requested to the PubSub service, +but you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Delete item with id ``123456`` from a node:: + + $ li pubsub delete -n test_node -i 123456 + +edit +==== + +Edit the raw XML of an item payload using your local editor (the one set in ``$EDITOR``). + +If you don't change anything or publish an empty blog post, the edition will be cancelled. + +:ref:`draft_common` commands can be used. + +example +------- + +Edit the last note in our custom node:: + + $ li pubsub edit -n notes -L + +subscribe +========= + +Subscribe to a node. + +Subscription is used to get notifications from the node in case of new/updated item or +deletion. + +example +------- + +Subscribe to an information blog:: + + $ li pubsub subscribe -n informations -s pubsub.example.net + +unsubscribe +=========== + +Unsubscribe from a node. + +example +------- + +Unsubscribe from an information blog:: + + $ li pubsub unsubscribe -n informations -s pubsub.example.net + +subscriptions +============= + +Retrieve subscriptions for all nodes on a service. + +``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if +it has subscription with multiple subIDs). + +example +------- + +Retrieve all subscriptions on a pubsub service:: + + $ li pubsub subscriptions -s pubsub@example.net + +affiliations +============= + +Retrieve affiliations for all nodes at a service. + +``-n NODE, --node NODE`` can be used to request affiliation for a specific node. + +examples +-------- + +Retrieve all affiliations at a pubsub service:: + + $ li pubsub affiliations -s pubsub@example.net + +Retrieve affiliation for the ``notes`` node:: + + $ li pubsub affiliations -s pubsub@example.net -n notes + +search +====== + +Search items corresponding to one or more filter(s). + +``search`` will check all items (or some of them according to options used) from one or +several nodes (several nodes can be checked if recursion is used, see below). For each +item the given filters will be checked, and all corresponding items will be returned. + +This is a resource intensive method (both for server and client), use with caution, and +use MAM to do searching when suitable. + +filters +------- + +To do a search you one or more filters. Filters are checked in the order in which they are +specified. You can use 4 kinds of filters: + +``-t TEXT, --text TEXT`` + do a full-text search. If *TEXT* is appearing anywhere in the item (including in XML + tags or arguments), the item is selected + +``-r EXPRESSION, --regex EXPRESSION`` + do a regular expression search. `Python standard re module`_ is used internally, so you + can use its syntax. + +``-x XPATH, --xpath XPATH`` + use an `XPath version 1.0`_ expression to filter the query. You can have a look at + `Wikipedia XPath page`_ for a user friendly introduction. + +``-P PYTHON_CODE, --python PYTHON_CODE`` + use a Python expression to do a test. The expression must return a boolean (``True`` to + keep item, ``False`` otherwise). From within the Python expression 3 variables are + defined: ``item`` which contain the raw item as a string, and ``item_xml`` which is the + parsed XML as an lxml ``etree.Element`` and ``etree`` which is the ``lxml.etree`` module. + +.. _Python standard re module: https://docs.python.org/3.7/library/re.html +.. _XPath version 1.0: https://www.w3.org/TR/1999/REC-xpath-19991116/ +.. _Wikipedia XPath page: https://en.wikipedia.org/wiki/XPath + +filter modifiers +---------------- + +Before each filter you can specify one or more filter modifiers. A modifier will change +filter behaviour, it's a flag which can be used either without argument (then it will +activate the flag), or with an explicit boolean value (i.e. ``true`` or ``false``). + +The available filters are: + +``-C [BOOLEAN], --ignore-case [BOOLEAN]`` + (don't) ignore case. Filters are normally case sensitive, this modifier change this + behaviour. + +``-I [BOOLEAN], --invert [BOOLEAN]`` + (don't) invert effect of following filters. This is applying a logical ``NOT`` to the + filter. This means that instead of keeping item matching the filter, it will keep the + items which are **not** matching the filter. + +``-A [BOOLEAN], --dot-all [BOOLEAN]`` + (don't) use `DOTALL`_ option for regex. This filter only makes sense before a + ``--regex`` expression. + +``-k [BOOLEAN], --only-matching [BOOLEAN]`` + (don't) keep only the matching part of the item. Normally the whole item is returned, + with this flag, only the part matching the filters are kept. + +.. _DOTALL: https://docs.python.org/3.7/library/re.html#re.DOTALL + +actions +------- + +Once filters are set, you may indicate what do to with the found items. By default they +are printed, but you can also use an other li command, or even an external tool. + +The following actions are available: + +``print`` (default) + pretty print the found items. + +``exec`` + use the given li command on each found item. Everything after the ``exec`` is used to + indicate the command and arguments to use (you must not specify ``li``, use the command + directly). The service, node and item will be set to match the found item. + +``external`` + pipe the raw XML of each item to the given command. Everything after the ``external`` + action is used to indicate the command and arguments to use. + +recursive search +---------------- + +By default, only items in the given node will be filtered, but if you specify a recursion +depth > 0 (using ``-D MAX_DEPTH, --max-depth MAX_DEPTH``), every node linked in item will +be checked too, then node linked in linked item and so on until depth level is reached. + +For instance, if you want to find all comments of a blog node containing an http(s) link, +you can do that:: + + $ li pubsub search -n urn:xmpp:microblog:0 -s user@example.net -D 1 -r 'https?://' + +examples +-------- + +Finding all items containing the text "something interesting" in personal blog:: + + $ li pubsub search -n urn:xmpp:microblog:0 -M -1 -t "something interesting" + +Find which blog items in the last 20 have a body with less than 200 characters (note that +body can be either ``<title>`` or ``<content>``, see `XEP-0277`_ for details). Here we use +a python expression on the text of the body to count the number of characters:: + + $ li pubsub search -n urn:xmpp:microblog:0 -M 20 --python "len((item_xml.find('.//{http://www.w3.org/2005/Atom}content[@type=\"text\"]') or item_xml.find('.//{http://www.w3.org/2005/Atom}title[@type=\"text\"]')).text) < 200" + +Find items published by ``toto@example.net`` among last 30 on a blog node, and use +``pubsub blog`` command to retrieve id and title. We use ``-N`` to specify the ``pubsub`` +namespace which is used in the XPath expression, then we use ``exec`` to run ``blog get -k +title -k id`` on found items:: + + $ li pubsub search -n some_blog_node -s pubsub.example.net -M 30 -N pubsub http://jabber.org/protocol/pubsub -x '/pubsub:item[starts-with(@publisher, "toto@example.net")]' exec blog get -k title -k id + +Find items which have **NOT** a title among last 30 items in our personal blog. As +explained in `XEP-0277`_ Atom's ``<title>`` is always used (even if there is only a body +and no title), so we actually look for items without ``<content>``. We do that with an +XPath looking for this ``atom:content`` element, then we use the ``-I [BOOLEAN], --invert +[BOOLEAN]`` to filter out elements which match.:: + + $ li pubsub search -n urn:xmpp:microblog:0 -M 30 -I -x //atom:content -N atom http://www.w3.org/2005/Atom + +Display authors names from last 10 items and their comments, using the ``-k [BOOLEAN], +--only-matching [BOOLEAN]`` modifier to only display the data we need. We use ``-D 1`` to +do a recursive search of level 1, which will also look into comments nodes (using last 10 +items there too):: + + $ li pubsub search -n urn:xmpp:microblog:0 -M 10 --only-matching -x //atom:author/atom:name -N atom http://www.w3.org/2005/Atom -D 1 + +.. _XEP-0277: https://xmpp.org/extensions/xep-0277.html + +transform +========= + +Modify items using an external command. + +``transform`` will retrieve requested items, and will send each of them to the standard +input (stdin) of the specified command. The output of the command will be used, it can be +3 things: + +- a raw XML of the modified item, in which case the item will be republished +- the string ``SKIP``, in which case the item will be ignored +- the string ``DELETE``, in which case the item will be retracted + +By default a dry run is done, which means that no item is modified or deleted. To actually +do the transformation, you have to use ``--apply`` argument. + +If you have to modify the ``publisher`` of an item, you need specific privileges. The +``--admin`` allows you do to that, but it must be supported by your PubSub service +(currently only ``SàT PubSub`` supports this non standard feature). + +To modify all items of a node, use the ``-A, --all`` option. This will use `RSM`_ +repetitively until all items are treated. Of course that means that your PubSub service +must support RSM. The items being republished, they will reappear on top of your node, +that's why it is recommended to use ``--order-by creation`` option when supported by the +service, to keep consistent order and avoid transforming the same items several times. + +If the command you're using exit with a non zero code, the process will stop. Use ``-I, +--ignore_errors`` if you want to continue transformation even if an non zero code is +returned. + +.. _RSM: https://xmpp.org/extensions/xep-0059.html + +example +------- + +Imagine that you want to replace all occurrences of "sàt" by "Salut à Toi" in your personal blog. You first create a Python script like this: + +.. sourcecode:: python + + #!/usr/bin/env python3 + + import sys + item_raw = sys.stdin.read() + if not "sàt" in item_raw: + print("SKIP") + else: + print(item_raw.replace("sàt", "Salut à Toi")) + +And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make is executable +with ``chmod +x ~/expand_sat.py``). + +To be sure it's safe, you can first do a dry-run and check the result:: + + $ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py + +Once you have checked that you have the expected behaviour, you can apply the +transformations:: + + $ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py + +And that's it. You can use the same technique for more complex transformations, including +modifying the XML (with Python, you can easily do that with standard +``xml.etree.ElementTree`` module or with ``lxml.etree``). + +uri +=== + +Build an XMPP URI linking to a PubSub node or item. + +example +------- + +Build a link to personal blog:: + + $ li pubsub uri -n urn:xmpp:microblog:0 + +node +==== + +Subcommands for node management. Please check :ref:`libervia-cli_pubsub_node`. + +hook +==== + +Subcommands for hooks management. Please check :ref:`libervia-cli_pubsub_hook`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub_hook.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,96 @@ +.. _libervia-cli_pubsub_hook: + +==================================== +pubsub/hook: PubSub hooks management +==================================== + +``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks +are user actions launched on specific events. + +3 types of hooks can be used: + +``python`` + A Python module is expected as argument. The module must be available in Python path, + and it must have a ``hook`` function. + +``python_file`` + A path to a Python script is expected as argument. The script must contain a ``hook`` + function. + +``python_code`` + Python code which will be directly executed. 3 variables will be set: ``host`` which + contain the main SàT instance, ``client`` which contain the session attached to the + profile, and ``item`` which contain the item attached to the event. + +.. note:: + + Hooks are executed in SàT context, and must be asynchronous. If they block, the whole + SàT execution will be blocked. They have access to everything, so don't run a code that + you don't absolutely trust. + +.. note:: + + Only ``python_file`` type is currently implemented + +.. note:: + Hook is an experimental feature, the way to use it may change in the future. + +create +====== + +Create a hook of given type. Type is specified with ``-t {python,python_file,python_code}, +--type {python,python_file,python_code}`` and a positional arguments is expected, which +depends on the chosen type. + +By default the hook is temporary (it will be lost if the profile is disconnected), but you +can make is persistent accross reconnexions if you use the ``-P, --persistent`` argument. + +example +------- + +Install a persistent hook on blog node, using the Python script named +``do_something_neat.py`` in ``$HOME`` directory:: + + $ li pubsub node hook create -n urn:xmpp:microblog:0 -t python_file --persistent ~/do_something_neat.py + +delete +====== + +Delete one hook or all of them. To delete a hook, specify its type and argument (the that +you have used with ``create``). If you use empty ``--type`` and ``--arg`` all hooks will +be removed. + +example +------- + +Delete the ``do_something_neat.py`` hook:: + + $ li pubsub node hook delete -n urn:xmpp:microblog:0 -t python_file --arg ~/do_something_neat.py + +list +==== + +List registered hooks. The output will give the following informations: + +service + PubSub service on which the hook is attached. + +node + PubSub node on which the hook is attached. + +type + hook type + +arg + hook arguments (dependant of hook type) + +persistent + boolean indicating is the hook persist accross sessions. + +example +------- + +Get PubSub hooks registered for this profile in JSON:: + + $ li pubsub hook list -O json +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub_node.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,126 @@ +.. _libervia-cli_pubsub_node: + +==================================== +pubsub/node: PubSub nodes management +==================================== + +``node`` is a subcommands grouping all PubSub commands related to node management. For +details on ``pubsub`` command itself, refer to :ref:`libervia-cli_pubsub`. + +info +==== + +Get settings of the node. Use ``-k KEYS, --key KEYS`` to select data to print. + +examples +-------- + +Get informations on our personal microblog node:: + + $ li pubsub node info -n urn:xmpp:microblog:0 + +Only print ``access_model`` and ``publish_model``:: + + $ li pubsub node info -n urn:xmpp:microblog:0 -k access_model -k publish_model + +.. _libervia-cli_pubsub_node_create: + +create +====== + +Create a node. Node configuration can be specified using ``-f KEY VALUE, --field KEY +VALUE`` where ``KEY`` is a pubsub option. By default the ``pubsub#`` prefix will be +appended, as it is used with standard options (see `XEP-0060`_ for more details); to +change this behaviour, use the ``-F, --full-prefix`` flag. + +.. _XEP-0060: https://xmpp.org/extensions/xep-0060.html + +example +-------- + +Create a node called ``notes`` with a ``whitelist`` access model (so only you and people +you may authorize later can access it):: + + $ li pubsub node create -n notes + +purge +===== + +Remove all items from a node (but don't delete the node). + +A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Remove all items from a blog comments node (in other words, removing all comments while +letting the node so people can add new comments):: + + $ li pubsub node purge -n "urn:xmpp:microblog:0:comments/123-456-789" + +delete +====== + +Delete a node (note that this will delete definitively all items that where published to +this node). + +A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Delete the ``temporary_notes`` node:: + + $ li pubsub node delete -n temporary_notes + +set +=== + +Update a node configuration. + +Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` argument +where ``KEY`` is a PubSub option. If ``KEY`` doesn't start with ``pubsub#`` prefix, it is +added automatically, except if ``-F, --full-prefix`` argument is used (in which case the +``KEY`` is used as specified. + +example +------- + +Make the ``public_notes`` node accessible to the world:: + + $ li pubsub node set -n public_notes -f access_model open + +import +====== + +Import a raw XML containing items to create in the node. The path to the XML file is used +as positional argument. + +The XML file must contain full `<item>` element for each item to import. The output of ``pubsub get`` can be used directly. + +If you want to change publisher of one or more items (i.e. if you want to use an other ``jid`` than the jid of the profile as publisher), you must use the ``--admin`` arguments. This needs a PubSub service supporting this feature (and you must of course be an administrator of this service). The new publisher must be allowed to publish to the node. + +example +------- + +Import a node backup which has previously been saved using ``li blog get -M -1 -n +some_node > some_node_backup.xml``:: + + $ li pubsub node import -n some_node ~/some_node_backup.xml + +.. note:: + + If your node is big, -M 1 option is not adapted as it will get all items at once and + may be blocked by your server stanza size limit. The possibility to use RSM to + retrieve all items by pages is planned in a future version. + +affiliations +============ + +Subcommands for node affiliations management. Please check :ref:`libervia-cli_pubsub_node_affiliations`. + +subscriptions +============= + +Subcommands for node subscriptions management. Please check +:ref:`libervia-cli_pubsub_node_subscriptions`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub_node_affiliations.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,40 @@ +.. _libervia-cli_pubsub_node_affiliations: + +======================================================= +pubsub/node/affiliations: nodes affiliations management +======================================================= + +``affiliations`` is a subcommand handling the affiliations of a node (not to be confused +with ``pubsub affiliations`` which handle the affiliations of a PubSub service). + +get +=== + +Retrieve entities affiliated to this node and their role. + +example +------- + +Get affiliations of a node:: + + $ li pubsub node affiliations get -n some_node + +set +=== + +Set affiliation of an entity on a node. Affiliations are specified with ``-a JID +AFFILIATION`` argument. Check `XEP-0060 affiliations`_ for allowed values for +``AFFILIATION``. Use ``none`` to remove an affiliation. + +.. _XEP-0060 affiliations: https://xmpp.org/extensions/xep-0060.html#affiliations + +example +------- + +If we have a whitelisted node ``some_whitelisted_node``, we can allow +``louise@example.net`` to publish on it (by setting her role as ``publisher``), and +``pierre@example.net`` to access it (by setting his role as ``member``) using the +following command:: + + $ li pubsub node affiliations set -n some_whitelisted_node -a louise@example.net + publisher -a pierre@example.net member
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub_node_schema.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,59 @@ +.. _libervia-cli_pubsub_node_schema: + +========================================= +pubsub/node/schema: nodes schema handling +========================================= + +``node schema`` is an experimental feature to associate a data form with a PubSub node, and +reject items not following this form. This feature is currently only available with SàT +PubSub. + +Those commands can only be used by an owner of the node. + +set +=== + +Set the schema of a node. The raw schema is written directly as positional argument. + +example +------- + +Set the schema for tickets node using the file ``tickets_schema.xml`` from ``$HOME`` +directory. Shell substition is used here to put the content of the file in the positional +argument:: + + $ li pubsub node schema set -n org.salut-a-toi.tickets:0 -s pubsub.example.org "$(<~/test_schema.xml)" + + +edit +==== + +Edit the schema of a node using your local editor (the one set in ``$EDITOR``). + +If you don't change anything or publish an empty schema, the edition will be cancelled. + +:ref:`draft_common` commands can be used. + +example +------- + +Edit the tickets node schema:: + + $ li pubsub node schema edit -n org.salut-a-toi.tickets:0 -s pubsub.example.org + + +example +------- + +get +=== + +Retrieve schema of a node. + +example +------- + +Get schema of tickets and save it to a file named ``tickets_schema.xml`` in ``$HOME`` +directory:: + + $ li pubsub node schema get -n org.salut-a-toi.tickets:0 -s pubsub.example.org > ~/tickets_schema.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/pubsub_node_subscriptions.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,43 @@ +.. _libervia-cli_pubsub_node_subscriptions: + +======================================================== +pubsub/node/affiliations: nodes subscriptions management +======================================================== + +``subscriptions`` is a subcommand handling the subscription to a node. + +Those commands can only be used by an owner of the node. + +get +=== + +Retrieve subscriptions to a node. + +example +------- + +Get subscription from ``some_node``:: + + $ li pubsub node subscriptions get -n some_node + +set +=== + +Set subscriptions to a node. Subscriptions are specified with ``-S JID [SUSBSCRIPTION] +[JID [SUSBSCRIPTION] ...], --subscription JID [SUSBSCRIPTION] [JID [SUSBSCRIPTION] ...]`` +where ``JID`` is the jid of the entity to change subscription state, and ``SUBSCRIPTION`` +is a subscription state (on of ``subscribed``, ``pending``, ``none``) as specified in +`XEP-0060 Subscription State`_. If ``SUBSCRIPTION`` is not specified, it default to +``subscribed``. + +.. _XEP-0060 Subscription State: https://xmpp.org/extensions/xep-0060.html#substates + +example +------- + +Subscribe Louise with her new address at ``louise@example.org`` and remove her +subscription from old ``louise@example.com``:: + + $ li pubsub node subscriptions set -n some_node -S louise@example.org subscribed louise@example.com none + +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/roster.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,145 @@ +================================ +roster: manager an entity roster +================================ + +"Roster" is the name used in XMPP for the contact list. In addition to list of contacts, +you have also data like subscription information or groups associated to a contact. + +Groups are simple strings associated to one or more contacts (e.g. "friends" or "family"). + +Subscription is the mechanism to get presence information of an entity. When you add a +contact to your roster, most XMPP clients also do a presence subscription request, than +the entity may accept or deny. If a presence subscription is accepted, the subscribed user +can see when the other entity is online, and its presence status. + +get +=== + +Show the current roster. By default only a display name and JIDs are displayed, but you +can increase verbosity to also display groups, or all other metadata. + +The short name shown next to jid is either the ``name`` specified in roster, or the node +part of the jid. If none of them exist, only the entity JID is shown. + +The following metadata may be displayed: + +groups + group the entity belong too +ask + true if a presence subscription request has been sent (but not answered yet) +from + the contact has a subscription to user presence (i.e. your contact can see when you're + online and your presence status) +to + the user has a subscription to the contact presence (i.e. you can see when you're + contact is online and his/her presence status) + +examples +-------- + +Get roster of default profile and display groups:: + + $ li roster get -v + +Get roster of default profile and display all metadata:: + + $ li roster get -vv + +Get roster or default profile and show the result in JSON:: + + $ li roster get -O json + +set +=== + +Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being +the user chosed name to use with a contact. + +By default, values are appended, i.e. if ``name`` is not set it won't delete existing one, +and ``groups`` are appended to existing one. However, if you use the ``-R, --replace`` +option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n +NAME, --name NAME`` option, the former one will be deleted, and any former group no added +using ``-g GROUP, --group GROUP`` will be removed). + +examples +-------- + +Set a name used to privately identify your contact Louise:: + + $ li roster set -n Enjolras louise@example.net + +Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``:: + + $ li roster set --replace -g friends -g housemates pierre@example.net + +delete +====== + +Remove an entity from roster. + +examples +-------- + +Remove John from your roster:: + + $ li roster delete john@example.net + +stats +===== + +Show some statistics about the profile roster. The number of contacts per server is shown, +with a percentage of contacts on this server compared to the total number of contacts. +This can notably be helpful to see if there is a concentration of your contacts in a +specific server or gateway. + +Other more or less useful numbers are shown, they are self explaining. + +example +------- + +Get statistic for the default profile:: + + $ li roster stats + +purge +===== + +This command is used to remove from the roster all contacts which have no subscription or +only partial subscription. + +By default, only contacts without subscription at all are removed. With ``--no_from`` you +also remove contacts which have no subscription to you (but you have a subscription to +them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but +who are subscribed to you). + +example +------- + +Remove all contacts from default profile which have no subscription at all or from which +the default profile is not subscribed to:: + + $ li roster purge --no_to + +resync +====== + +SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on +client connection. This means that once the roster has been retrieved, on each following +connection, only the difference of contacts (i.e. which new or removed contacts) is +received. + +This command does a full resynchronisation of the roster, or in other words it requests +the whole roster and save it, replacing the list built with versioning. ``resync`` is +mostly useful for developers and end-user should not need this command, as roster +versioning is supposed to work fine and the roster should be synchronised correctly on +startup. But if for any reason you suspect that your current roster list is corrupted, you +may use it to be sure that a full resynchronisation is done. + +.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6 + +exemple +------- + +Do a full resynchronisation of default profile's roster:: + + $ li roster resync
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/shell.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,208 @@ +======================== +shell: use SàT with REPL +======================== + +``shell`` launch a read–eval–print loop (REPL) with some helpers to launch li commands. +This is useful if you are willing to a session when you'll use several commands in a row +(for e.g. to inspect something on a PubSub service). + +start the shell +=============== + +To start the shell, you just have to enter ``li shell``. You can eventually specify a +profile to use an other one than the default one by entering ``li shell -p +<some_profile>``. + + +.. _libervia-cli_shell_use: + +use the shell +============= + +Once in the shell, you can launch a command by entering it as usual (without having to +specify ``li``). For instance to get last 2 blog posts from your personal blog, you just +have to enter:: + + > blog get -m 2 + +There are 2 kinds of commands in the shell: + +- **shell commands** which are command to manipulate the shell itself +- **li commands** which are the classic commands that you use with li + +The most important thing to remember is that you can use ``?`` (or ``help`` which is +equivalent) to get the list of commands (shell + li), and ``?<command>`` (or ``help +<command>``) to get information on a shell command. For li commands, you can use the usual +``--help`` argument. + +You may move in the commands hierarchy using ``cmd`` which can be seen as something +roughly equivalent to ``cd`` for the filesystem. for instance if you know you'll work with +XMPP blogs, you can enter:: + + > cmd blog + +Then you'll be in the blog hierarchy, you can check that by entering ``?``. From there you +can use blog commands directly, like in this example to retrieve last 2 blog posts:: + + blog> get -m 2 + +You can even go further, e.g. if you know that you'll do several ``get`` command (in this +can you'll only have to specify the arguments of ``get``):: + + blob> cmd get + blog/get> -m 2 + +You can use ``/`` with ``cmd``, including as first character to indicate that you want to +start from root:: + + blog/get> cmd /pubsub + pubsub> cmd node/info + +Similarly, you can use ``..`` to move to parent command:: + + pubsub/node/info> cmd .. + +One of the interesting feature of shell is that you can fix an argument, i.e. indicate +the value to use in the next commands. For instance if you're willing to work on a +specific node, you can set its value with ``use``:: + + blog> use node some_interesting_node + +Then you won't have to specify it anymore for each command. The name of the argument to +fix must be the long form. To check which arguments are fixed, just enter ``use`` without +argument. If an argument is fixed but not used in a command, it will be ignored. + +To clear a fixed argument, you have the ``use_clear`` command. To clear the ``node`` +argument set above, just enter:: + + blog> use_clear node + +Without argument, all fixed arguments will be cleared. + + +Shell commands +============== + +Below is a description of shell commands. + + +cmd +--- + +Move in the command hierarchy, this avoid to type again a command if you know you'll use +it several times. See libervia-cli_shell_use_ for explanation and examples + +do +-- + +Launch a li command. By default the command is launched if you enter directly its name and +arguments, but if a command or argument conflict with a shell command, the shell command +will be launched instead. The ``do`` command avoid such a situation by always launching a +li command:: + + > do blog get -m 2 + +exit +---- + +Quit the shell (alias of ``quit``). + +help (alias ``?``) +------------------ + +Give information on available commands or on a specific command, see libervia-cli_shell_use_ for +more explanations. + +examples +^^^^^^^^ + +Get general help:: + + > ? + +Get help on ``do`` command:: + + > ?do + +quit +---- + +Quit the shell + +shell (alias ``!``) +------------------- + +Launch an external command. + +example +^^^^^^^ + +Print a calendar with ``cal``:: + + > !cal + +use +--- + +Fix the value of an argument, which will then be set for all following commands, see +libervia-cli_shell_use_ for more explanations. + +Without argument, show all fixed arguments + +examples +^^^^^^^^ + +Fix the PubSub node (the long name of the argument is used, so it will go to ``--node``):: + + pubsub> use node some_intersting_node + +Show all fixed arguments:: + + > use + +use_clear +--------- + +Unfix the value of an argument (i.e. use the normal default value). Without argument, +it unfixes all arguments. + +examples +^^^^^^^^ +Clear the node:: + + pubsub> use_clear node + +Clear all arguments:: + + > use_clear + +verbose +------- + +Without argument, show if verbose mode is activated. With an argument evaluating to a +boolean, activate or deactivate this mode. + +In verbose mode, the fixed arguments and the command launched are printed before launching +a li command. + +examples +^^^^^^^^ + +Show if verbose mode is activated:: + + > verbose + +Activate verbose mode:: + + > verbose on + +version +------- + +Print current version of li/Salut à Toi. + +whoami +------ + +Show the name of the connected profile (the one set with ``--profile`` when launching the +shell). This profile will be used as default profile.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/ticket.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,72 @@ +================================= +ticket: create and manage tickets +================================= + +Ticket is a generic tools to create items with metadata and states (where state can be +``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs +management. + +get +=== + +Retrieve one or more tickets and display them. A project may use magic string in README to +indicate PubSub service and node to use, in which case use just need to be in the +directory of the project. + +examples +-------- + +Retrieve last 5 tickets (ordered by creation) from a project using magic string in README:: + + $ li ticket get -m 5 -o creation + +Retrieve the ticket with id ``123`` on service ``pubsub.example.org``:: + + $ li ticket get -s pubsub.example.org -i 123 + + + +import +====== + +Import tickets from an external source. This works in the same way as +:ref:`libervia-cli_blog_import`: you need to specify an importer and a data location. If you let +both positional argument empty, you'll get list of importers, if you specify importer but +not data location, you'll get a description on how the importer works. + +If you want to see a progress bar for the import, use the ``-P, --progress`` option, this +is recommended for most imports. + +Some importers may have specific option (check description for details), you can specify +them with ``o NAME VALUE, --option NAME VALUE`` + +When you import a ticket, the ticket will be created according to the schema of the PubSub +node. By default, the metadata of the original ticket will be put to the one of the same +name in the dest PubSub item. But of course the schema of your destination PubSub node may +differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD +DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done +(``IMPORTED_FIELD is the name of the field in the original ticket, while ``DEST_FIELD`` if +the name of the field in your node schema). + + +examples +-------- + +Get list of ticket importers:: + + $ li ticket import + +Get description of ticket importer for Bugzilla:: + + $ li ticket import bugzilla + +Import tickets from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the +``pubsub.example.org`` PubSub service. We use default tickets node and want a progression +bar:: + + $ li ticket import -P -s pubsub.example.org ~/bugzilla_export.xml + +Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to +the field ``assigned_to`` in our schema:: + + $ li ticket import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-cli/uri.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,39 @@ +================================ +uri: XMPP URI parsing/generation +================================ + +URI commands are helper to easily parse/build XMPP URIs. + +parse +===== + +Parse an XMPP URI, and print different parts. + +When possible, the ``type`` of URI is shown (e.g. ``pubsub``) and the ``sub_type`` (e.g. +``microblog``). + +The ``path`` is always displayed (see `RFC 5122 Path section`_ for details). + +If suitable, you'll also get data like ``node`` (for a PubSub URI). + +.. _RFC 5122 Path section: https://tools.ietf.org/html/rfc5122#section-2.4 + +examples +-------- + +Parse a blog URI:: + + $ li uri parse "xmpp:somebody@example.org?;node=urn%3Axmpp%3Amicroblog%3A0" + +build +====== + +Build an XMPP URI according to arguments. 2 positional arguments are expected: ``type`` +and ``path``. For now, only ``pubsub`` type is supported. + +examples +-------- + +Build XMPP URI for a blog:: + + $ li uri build pubsub somebody@example.org -f node urn:xmpp:microblog:0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libervia-tui/index.rst Sun Mar 21 18:23:58 2021 +0100 @@ -0,0 +1,153 @@ +.. _primitivus-documentation: + +========== +Primitivus +========== + +``Primitivus`` is the TUI (Terminal User Interface) frontend of Salut à Toi + +Overview +======== + +``Primitivus`` is a text based frontend. It is specially adapted for systems without +graphical environments (e.g. servers), for low bandwidth remote shells (e.g. ssh) or for +people who like straightforward interfaces without distracting images or animations. + +For the moment, Primitivus implements one 2 one chat, group chat (also called *MUC* for +Multi-Users Chat), and some related features (end 2 end encryption, bookmarks, gateways +interaction, file sending, etc.). + +Usage +===== + +Primitivus is modal (vi-like), one can switch from one mode to another +in the same way as in vi/vim: + +- From any mode, press ``[Esc]`` to switch to normal mode. +- From normal mode, press ``:`` to switch to command mode. +- From normal mode, press ``i`` to switch to insert mode – the one you + use to write messages to your contacts. + +Primitivus can be handled either with the mouse, in a very intuitive way, or with the +keyboard. Below, the keyboard shortcuts are explained. + +Keyboard handling +----------------- + +- ``+`` means that 2 keys must be pressed at the same time. Example: ``CTRL + N`` means that + you must press Control key and ``N`` at the same time +- ``,`` means that a key must be pressed after the previous combination. Example: + ``CTRL + F, M`` means that you must press control key and ``F`` at the same time, release + them, then press ``M`` +- keys with ``SHIFT`` also work without ``SHIFT`` if ``[CapsLock]`` is set. + +Main keys +~~~~~~~~~ + +``[Tab]`` and/or ``CTRL + up/down arrows`` + change focus +``CTRL + X`` + quit Primitivus +``CTRL + F, 1`` or ``CTRL + F, M`` + focus on the menu +``CTRL + F, 2`` or ``CTRL + F, B`` + focus on the roster or the chat window +``CTRL + F, 3`` or ``CTRL + F, E`` + focus on the edition line +``ALT + M`` + display/hide the menu +``CTRL + N`` + show the next notification +``CTRL + S`` + hide/redisplay a pop-up window temporarily +``CTRL + D`` + enter debug mode (development versions only) +``F2`` + hide/display the roster +``CTRL + L`` + refresh the screen + +Chat rooms +~~~~~~~~~~ + +To use those keyboard shortcuts, your cursor must be in a chat room. + +``ALT + J`` + join a chat room +``ALT + P`` + hide/display the list of participants +``ALT + T`` + hide/display timestamps +``ALT + N`` + use/don't use short nicks +``ALT + L`` + hide/display frame decorations +``ALT + S`` + change the room's topic appearance by switching between: + - one single line (the topic is cut if it's too long) + - the full topic + - topic hidden +``SHIFT + G`` + go to the end (bottom) of your history (note that this is UPPERCASE ``G``) + + +Edition line +~~~~~~~~~~~~ + +``CTRL + A`` or ``[Home]`` + move the cursor at the beginning of the line +``CTRL + E`` or ``[End]`` + move the cursor at the end of the line +``CTRL + K`` + erase the line, starting at the cursor's position +``CTRL + W`` + erase the last word +``S + [Tab]`` + invoke completion (dependent on the context) +``up/down arrows`` + browse sent messages history + +Contacts +~~~~~~~~ + +``ALT + D`` + hide/display offline contacts +``ALT + S`` + hide/display contacts' status messages + +Card game +~~~~~~~~~ + +``[space]`` + select a card + +Commands +~~~~~~~~ + +The following commands must be typed in command mode (type ``[Esc]`` to switch to normal +mode, then the ``:`` at the beginning of the command will switch to command mode). + +``:quit`` + quit Primitivus +``:messages`` + display log messages (see also the logging configuration) + +.. + FIXME: :presence and :status are currently disabled in Primitivus + ``:presence [status]`` + set your presence status. Invoked without argument, a pop-up will allow you to choose your presence status; otherwise, you can use the following arguments: + - ``online`` + - ``chat`` (free to chat) + - ``away`` (away from keyboard) + - ``dnd`` (do not disturb) + - ``xa`` (extended away) + ``:status [message]`` + set your status message. Invoked without argument, a pop-up will allow you to enter a message. + +``:history <size>`` + set the number of lines of history to display in the chat window (``:history 0`` to clear the window) +``:search <filter>`` + do a full text search in this conversation/room. The room will be cleared an only + messages corresponding to ``<filter>`` will be show. Use ``:history <size>`` to + restore normal history +
--- a/doc/overview.rst Sun Mar 21 18:16:52 2021 +0100 +++ b/doc/overview.rst Sun Mar 21 18:23:58 2021 +0100 @@ -2,24 +2,24 @@ Overview ======== -To have a better understanding of Salut a Toi, this page gives a global view of what it is +To have a better understanding of Libervia, this page gives a global view of what it is and what are the important concepts linked to it. You don't need to read this to use it, but you can if you wish to understand "who is doing what". -Salut à Toi (or SàT) is a XMPP client. `XMPP`_ is an open standard used -for communication (notably instant messaging but not only). XMPP is a solid standard, -which is decentralised and federated. +Libervia is a XMPP client. `XMPP`_ is an open standard used for communication (notably +instant messaging but not only). XMPP is a solid standard, which is decentralised and +federated. -SàT is not only focusing on instant messaging, and aims to be a universal communication -tools. In other words, you can use SàT to chat, but also to blog publicly or privately, to +Libervia is not only focusing on instant messaging, and aims to be a universal communication +tools. In other words, you can use Libervia to chat, but also to blog publicly or privately, to share file, photo albums, to create events, to have discussion forum, etc. -SàT is actually a whole ecosystem, and is made in a way that you can use it with many +Libervia is actually a whole ecosystem, and is made in a way that you can use it with many different interfaces (or "frontends"). There is a common central part which is called the "backend", it handles most of the work, while frontends are mostly about the interactions with user(s). -To work, as SàT is a XMPP **client**, a XMPP **server** is needed. You can either run your +To work, as Libervia is a XMPP **client**, a XMPP **server** is needed. You can either run your own, or use an existing one (either public, or run by an organisation you belong to, like family server, run by a friend, your company, university, association, etc.). If you want to run your own server, there are already plenty of them and happily most of which are @@ -27,9 +27,9 @@ on the XSF website <https://xmpp.org/software/servers.html>`_ (the XSF or *XMPP Standards Foundation* being the non-profit organisation taking care of the XMPP standard). -So to summarise, Salut à Toi, or SàT, is a communication ecosystem. Technically, it is a -**XMPP client** which connect to an **XMPP server**. SàT itself works with a **backend** -and one or many **frontends**. +So to summarise, Libervia is a communication ecosystem. Technically, it is a **XMPP +client** which connect to an **XMPP server**. Libervia itself works with a **backend** and +one or many **frontends**. .. _XMPP: https://xmpp.org @@ -62,22 +62,23 @@ Bellow you'll see a list of the official frontends currently maintained: -Cagou ------ +Libervia Deskop/Mobile (Cagou) +------------------------------ -Cagou is the desktop/mobile frontend. It's probably the main interface for most users. It -is based on the `Kivy`_ framework and should run on most platforms (for now it is -officially tested only on GNU/Linux and Android phones and tablets). +Libervia Desktop (alias ``Libervia Mobile`` or ``Cagou``) is the desktop/mobile frontend. +It's probably the main interface for most users. It is based on the `Kivy`_ framework and +should run on most platforms (for now it is officially tested only on GNU/Linux and +Android phones and tablets). .. _Kivy: https://kivy.org -Libervia --------- +Libervia Web +------------ -Libervia is the web frontend, and is the second main interface for most users. This -frontend has the particularity to be in 2 parts: a server which serves HTTP content, and a -client which runs in the browser. So you have Libervia server which connect to SàT backend -which itself connect to the XMPP server, and your browser will connect to Libervia server. +The Web frontend is the second main interface for most users. This frontend has the +particularity to be in 2 parts: a server which serves HTTP content, and a client which +runs in the browser. So you have Libervia server which connect to Libervia backend which itself +connect to the XMPP server, and your browser will connect to Libervia server. In the browser, you can access the server in two ways: either directly with what we call **Libervia pages**, or with a JavaScript code in `single-page application`_ which is the @@ -88,56 +89,55 @@ dynamic contents). They aims to be simple and straightforward to use. The **Libervia client** is a highly dynamic web application, used to access more features. -It's more complete and may be well adapted if you want to let SàT running in a browser tab +It's more complete and may be well adapted if you want to let Libervia running in a browser tab for an extended period. -Please note that the current web application (SàT 0.7) will be completely rewritten for next 0.8 release. - Last but not least, Libervia is also the central part of the new **web framework** of -Salut à Toi. Indeed, in addition of being a frontend to SàT features (which is built with -this framework), you can create totally different websites which are integrated in SàT -(and so XMPP) ecosystem. This framework uses SàT template engine (based on `Jinja2`_) and +Libervia. Indeed, in addition of being a frontend to Libervia features (which is built with +this framework), you can create totally different websites which are integrated in Libervia +(and so XMPP) ecosystem. This framework uses Libervia template engine (based on `Jinja2`_) and makes the creation of decentralised and federated websites simple. Thanks to this framework, it's easy to experiment new ideas/features, or to change completely the look and feel of the Libervia frontend. -The `official SàT website`_ is made with Libervia web framework. +The `official Libervia website`_ is made with Libervia web framework. .. _single-page application: https://en.wikipedia.org/wiki/Single-page_application .. _Jinja2: http://jinja.pocoo.org/ -.. _official SàT website: https://salut-a-toi.org +.. _official Libervia website: https://salut-a-toi.org -Primitivus ----------- +Libervia TUI (Primitivus) +------------------------- -Primitivus is the Terminal User Interface (TUI). In other words, it works in console and -is intended for people at ease with it. Its text only interface has several advantages: -you get rid of many distracting things (like images), it works without graphical -environment installed (which is often the case on servers) and it works on distant shell -(like `ssh`_) while staying gentle with your bandwidth. +Libervia TUI (alias ``Primitivus``) is the Terminal User Interface. In other words, it +works in console and is intended for people at ease with it. Its text only interface has +several advantages: you get rid of many distracting things (like images), it works without +graphical environment installed (which is often the case on servers) and it works on +distant shell (like `ssh`_) while staying gentle with your bandwidth. -Primitivus is shipped with the backend, so it should be always available once SàT is +Primitivus is shipped with the backend, so it should be always available once Libervia is installed (but some distributions may provide it separately). -You can check :doc:`Primitivus documentation <primitivus/index>` for more details. +You can check :doc:`Libervia TUI documentation <libervia-tui/index>` for more details. .. _ssh: https://en.wikipedia.org/wiki/Secure_Shell -jp --- +Libervia CLI (jp) +----------------- -Jp is the Command Line Interface (CLI). It's a powerful tool which allows to do nearly -everything you can do with other frontends. Particularly useful if you want to check -something quickly, or if you want to do some automation. +Libervia CLI (alias ``li`` or ``jp``) is the Command Line Interface. It's a +powerful tool which allows to do nearly everything you can do with other frontends. +Particularly useful if you want to check something quickly, or if you want to do some +automation. -You can check :doc:`jp documentation <jp/index>` documentation for more details. +You can check :doc:`Libervia CLI documentation <libervia-cli/index>` documentation for more details. .. _glossary: Glossary ======== -While using SàT you may see some terms or concept. This section explain the most important +While using Libervia you may see some terms or concept. This section explain the most important ones. profile @@ -147,17 +147,17 @@ account, but you can have several profiles using the same XMPP account (with different parameters) even if this is not usual. -On a SàT installation used by a single user, the profiles are usually used for multiple +On a Libervia installation used by a single user, the profiles are usually used for multiple accounts. On a multi-users installations, there is usually one profile per user. -When you connect to a SàT frontend, you need to specify a profile and the associated password. The profile password is not the same as the password of the XMPP account. While this may sounds confusing, there are several reason why we use this notion of profile instead of directly the XMPP account/password: +When you connect to a Libervia frontend, you need to specify a profile and the associated password. The profile password is not the same as the password of the XMPP account. While this may sounds confusing, there are several reason why we use this notion of profile instead of directly the XMPP account/password: -- SàT needs to know the plain XMPP password to connect, and it is encrypted in database. +- Libervia needs to know the plain XMPP password to connect, and it is encrypted in database. The profile password is used to encrypt/decrypt it, this way only a `password hash`_ is stored and the XMPP password is encrypted `at rest`_. - As a further benefit, several passwords could be associated to the same profile (this - feature is currently not used in SàT). + feature is currently not used in Libervia). - profile password can be empty, in which case no password is requested when a profile is used @@ -186,7 +186,7 @@ bridge ------ -The "bridge" is the name used to design Salut à Toi's `IPC`_, or in other words the way +The "bridge" is the name used to design Libervia's `IPC`_, or in other words the way the backend communicate with frontends. Several bridges can be used, the default one being `D-Bus`_. @@ -205,47 +205,47 @@ .. _Perspective Broker: https://twistedmatrix.com/documents/current/core/howto/pb-intro.html .. _Twisted: https://twistedmatrix.com -SàT Media ---------- +Libervia Media +-------------- Most of the frontends use images or other media. To avoid duplication and to make the code -repositories lighter, those media are grouped in a separate repository. The SàT media +repositories lighter, those media are grouped in a separate repository. The Libervia media repository is available at https://repos.goffi.org/sat_media. You can also download media -at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where SàT media are +at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where Libervia media are installed must be specified in ``sat.conf`` in ``media_dir`` option of the ``[DEFAULT`` section. -SàT Templates -------------- +Libervia Templates +------------------ -SàT embeds a `Jinja2`_ template engine (see `Libervia`_ above). "SàT templates" refers to -the default templates (i.e. the official templates, the ones used in default Libervia pages). Those template may also be used by other frontends than Libervia (jp can use them with the :ref:`jp-output` arguments). +Libervia embeds a `Jinja2`_ template engine (see `Libervia Web`_ above). "Libervia templates" refers to +the default templates (i.e. the official templates, the ones used in default Libervia pages). Those template may also be used by other frontends than Libervia (jp can use them with the :ref:`libervia-cli_output` arguments). -SàT templates repository is available at https://repos.goffi.org/sat_templates, they can +Libervia templates repository is available at https://repos.goffi.org/sat_templates, they can also be downloaded at `PyPI <https://pypi.org/project/sat-templates/>`_ and will be installed automatically if you install Libervia. Related projects ================ -Some project are closely related to Salut à Toi, here is a list of official related +Some project are closely related to Libervia, here is a list of official related project. -SàT PubSub ----------- +Libervia PubSub +--------------- -Numerous features of Salut à Toi are taking profit of `PubSub`_ functionalities of XMPP. +Numerous features of Libervia are taking profit of `PubSub`_ functionalities of XMPP. Because PubSub implementations in the wild are not all on the same level, and some experimental features are sometimes explored, a PubSub service as been written -specifically for the needs of SàT (but it's not depending on SàT and any XMPP software can +specifically for the needs of Libervia (but it's not depending on Libervia and any XMPP software can use it). -SàT PubSub aims to be a feature complete, server-independent PubSub implementation, and +Libervia PubSub aims to be a feature complete, server-independent PubSub implementation, and try to be up-to-date with latest XMPP PubSub extensions. It is the privileged service to -use with SàT because it supports everything needed (but SàT can work with any XMPP PubSub +use with Libervia because it supports everything needed (but Libervia can work with any XMPP PubSub service, it will adapt itself to available features). -SàT PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by +Libervia PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by your server (see below). .. _PubSub: https://xmpp.org/about/technology-overview.html#pubsub @@ -254,23 +254,23 @@ XMPP Extension Protocols ------------------------ -For the needs of SàT or SàT PubSub, some `XMPP Extension Protocols`_ (or XEP) have been +For the needs of Libervia or Libervia PubSub, some `XMPP Extension Protocols`_ (or XEP) have been proposed and got an official number. The current list of extensions is: `XEP-0355`_: Namespace Delegation - This has been proposed for the needs of SàT PubSub, and allows the XMPP server to - "delegate" some features management to a third party service. It is needed to use SàT + This has been proposed for the needs of Libervia PubSub, and allows the XMPP server to + "delegate" some features management to a third party service. It is needed to use Libervia Pubsub as a PEP service. `XEP-0356`_: Privileged Entity - In the same spirit as previous one, this has been done so SàT PubSub could be used as a + In the same spirit as previous one, this has been done so Libervia PubSub could be used as a PEP service. This extensions allows a "component" (which is more or less a server generic plugin) to gain some privileged access to data such as presence information, roster or to send a message like if it was sent by the server. `XEP-0413`_: Order-By This extension is used to specify the sorting order in which a client wishes to retrieve - some results. It is notably used by SàT and SàT PubSub to retrieve items like blog posts + some results. It is notably used by Libervia and Libervia PubSub to retrieve items like blog posts or tickets in creation order or order of last modification. .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html @@ -284,19 +284,19 @@ Prosody modules have been created to implement the *Namespace Delegation* and *Privileged Entity* extensions mentioned above. If you use Prosody, you'll have to activate those 2 -modules to use SàT PubSub as a PEP service. +modules to use Libervia PubSub as a PEP service. .. _mod_privilege: https://modules.prosody.im/mod_privilege.html .. _mod_delegation: https://modules.prosody.im/mod_delegation.html -SàT official website --------------------- +Libervia official website +------------------------- The official website is made with Libervia web framework. You'll find it at https://repos.goffi.org/sat_web_site Salut ----- -Probably the smaller side project used by SàT, it is a simple users directory (registration must be done explicitly by users) using `XEP-0055`_ (Jabber Search). +Probably the smaller side project used by Libervia, it is a simple users directory (registration must be done explicitly by users) using `XEP-0055`_ (Jabber Search). You'll find it at https://repos.goffi.org/salut/
--- a/doc/primitivus/index.rst Sun Mar 21 18:16:52 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,153 +0,0 @@ -.. _primitivus-documentation: - -========== -Primitivus -========== - -``Primitivus`` is the TUI (Terminal User Interface) frontend of Salut à Toi - -Overview -======== - -``Primitivus`` is a text based frontend. It is specially adapted for systems without -graphical environments (e.g. servers), for low bandwidth remote shells (e.g. ssh) or for -people who like straightforward interfaces without distracting images or animations. - -For the moment, Primitivus implements one 2 one chat, group chat (also called *MUC* for -Multi-Users Chat), and some related features (end 2 end encryption, bookmarks, gateways -interaction, file sending, etc.). - -Usage -===== - -Primitivus is modal (vi-like), one can switch from one mode to another -in the same way as in vi/vim: - -- From any mode, press ``[Esc]`` to switch to normal mode. -- From normal mode, press ``:`` to switch to command mode. -- From normal mode, press ``i`` to switch to insert mode – the one you - use to write messages to your contacts. - -Primitivus can be handled either with the mouse, in a very intuitive way, or with the -keyboard. Below, the keyboard shortcuts are explained. - -Keyboard handling ------------------ - -- ``+`` means that 2 keys must be pressed at the same time. Example: ``CTRL + N`` means that - you must press Control key and ``N`` at the same time -- ``,`` means that a key must be pressed after the previous combination. Example: - ``CTRL + F, M`` means that you must press control key and ``F`` at the same time, release - them, then press ``M`` -- keys with ``SHIFT`` also work without ``SHIFT`` if ``[CapsLock]`` is set. - -Main keys -~~~~~~~~~ - -``[Tab]`` and/or ``CTRL + up/down arrows`` - change focus -``CTRL + X`` - quit Primitivus -``CTRL + F, 1`` or ``CTRL + F, M`` - focus on the menu -``CTRL + F, 2`` or ``CTRL + F, B`` - focus on the roster or the chat window -``CTRL + F, 3`` or ``CTRL + F, E`` - focus on the edition line -``ALT + M`` - display/hide the menu -``CTRL + N`` - show the next notification -``CTRL + S`` - hide/redisplay a pop-up window temporarily -``CTRL + D`` - enter debug mode (development versions only) -``F2`` - hide/display the roster -``CTRL + L`` - refresh the screen - -Chat rooms -~~~~~~~~~~ - -To use those keyboard shortcuts, your cursor must be in a chat room. - -``ALT + J`` - join a chat room -``ALT + P`` - hide/display the list of participants -``ALT + T`` - hide/display timestamps -``ALT + N`` - use/don't use short nicks -``ALT + L`` - hide/display frame decorations -``ALT + S`` - change the room's topic appearance by switching between: - - one single line (the topic is cut if it's too long) - - the full topic - - topic hidden -``SHIFT + G`` - go to the end (bottom) of your history (note that this is UPPERCASE ``G``) - - -Edition line -~~~~~~~~~~~~ - -``CTRL + A`` or ``[Home]`` - move the cursor at the beginning of the line -``CTRL + E`` or ``[End]`` - move the cursor at the end of the line -``CTRL + K`` - erase the line, starting at the cursor's position -``CTRL + W`` - erase the last word -``S + [Tab]`` - invoke completion (dependent on the context) -``up/down arrows`` - browse sent messages history - -Contacts -~~~~~~~~ - -``ALT + D`` - hide/display offline contacts -``ALT + S`` - hide/display contacts' status messages - -Card game -~~~~~~~~~ - -``[space]`` - select a card - -Commands -~~~~~~~~ - -The following commands must be typed in command mode (type ``[Esc]`` to switch to normal -mode, then the ``:`` at the beginning of the command will switch to command mode). - -``:quit`` - quit Primitivus -``:messages`` - display log messages (see also the logging configuration) - -.. - FIXME: :presence and :status are currently disabled in Primitivus - ``:presence [status]`` - set your presence status. Invoked without argument, a pop-up will allow you to choose your presence status; otherwise, you can use the following arguments: - - ``online`` - - ``chat`` (free to chat) - - ``away`` (away from keyboard) - - ``dnd`` (do not disturb) - - ``xa`` (extended away) - ``:status [message]`` - set your status message. Invoked without argument, a pop-up will allow you to enter a message. - -``:history <size>`` - set the number of lines of history to display in the chat window (``:history 0`` to clear the window) -``:search <filter>`` - do a full text search in this conversation/room. The room will be cleared an only - messages corresponding to ``<filter>`` will be show. Use ``:history <size>`` to - restore normal history -