doc: updated doc following global renaming

This commit is contained in:
Goffi 2021-03-21 18:23:58 +01:00
commit 6d15e23a31
36 changed files with 400 additions and 395 deletions

View file

@ -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

120
doc/libervia-cli/ad-hoc.rst Normal file
View file

@ -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

View file

@ -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

299
doc/libervia-cli/blog.rst Normal file
View file

@ -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

View file

@ -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"

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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`.

View file

@ -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"

173
doc/libervia-cli/file.rst Normal file
View file

@ -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`.

View file

@ -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`.

View file

@ -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

View file

@ -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

102
doc/libervia-cli/forums.rst Normal file
View file

@ -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

View file

@ -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

View file

@ -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

77
doc/libervia-cli/info.rst Normal file
View file

@ -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

119
doc/libervia-cli/input.rst Normal file
View file

@ -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

View file

@ -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

Some files were not shown because too many files have changed in this diff Show more