doc: updated doc following global renaming
This commit is contained in:
parent
8768429efc
commit
6d15e23a31
36 changed files with 400 additions and 395 deletions
75
doc/libervia-cli/account.rst
Normal file
75
doc/libervia-cli/account.rst
Normal 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
120
doc/libervia-cli/ad-hoc.rst
Normal 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
|
||||
47
doc/libervia-cli/avatar.rst
Normal file
47
doc/libervia-cli/avatar.rst
Normal 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
299
doc/libervia-cli/blog.rst
Normal 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
|
||||
98
doc/libervia-cli/bookmarks.rst
Normal file
98
doc/libervia-cli/bookmarks.rst
Normal 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"
|
||||
214
doc/libervia-cli/common_arguments.rst
Normal file
214
doc/libervia-cli/common_arguments.rst
Normal 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
|
||||
93
doc/libervia-cli/debug.rst
Normal file
93
doc/libervia-cli/debug.rst
Normal 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
|
||||
126
doc/libervia-cli/encryption.rst
Normal file
126
doc/libervia-cli/encryption.rst
Normal 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
|
||||
81
doc/libervia-cli/event.rst
Normal file
81
doc/libervia-cli/event.rst
Normal 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`.
|
||||
94
doc/libervia-cli/event_invitee.rst
Normal file
94
doc/libervia-cli/event_invitee.rst
Normal 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
173
doc/libervia-cli/file.rst
Normal 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`.
|
||||
108
doc/libervia-cli/file_share.rst
Normal file
108
doc/libervia-cli/file_share.rst
Normal 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`.
|
||||
56
doc/libervia-cli/file_share_affiliations.rst
Normal file
56
doc/libervia-cli/file_share_affiliations.rst
Normal 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
|
||||
38
doc/libervia-cli/file_share_configuration.rst
Normal file
38
doc/libervia-cli/file_share_configuration.rst
Normal 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
102
doc/libervia-cli/forums.rst
Normal 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
|
||||
36
doc/libervia-cli/identity.rst
Normal file
36
doc/libervia-cli/identity.rst
Normal 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
|
||||
94
doc/libervia-cli/index.rst
Normal file
94
doc/libervia-cli/index.rst
Normal 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
77
doc/libervia-cli/info.rst
Normal 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
119
doc/libervia-cli/input.rst
Normal 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
|
||||
109
doc/libervia-cli/invitation.rst
Normal file
109
doc/libervia-cli/invitation.rst
Normal 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
Loading…
Reference in a new issue