erebion/libervia-backend
Watch
1
0
Fork
You've already forked libervia-backend
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc (jp): jp commands are now fully documented:

Browse source 
rel 232
This commit is contained in:
Goffi 2019-10-01 22:49:06 +02:00
commit 7bfa63a751
35 changed files with 2976 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/configuration.rst
View file

@ -1,3 +1,5 @@
.. _configuration:
=============
Configuration
=============

75
doc/jp/account.rst Normal file
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``::
$ jp account create nestor@example.org some_password -p nestor
modify
======
Modify an existing XMPP account password. This will modify the XMPP account linked to the
given profile.
.. note::
Only the XMPP password on the server is changed, not the one registered in the
parameter of SàT. You may have to update the parameter of your profile if the new
password doesn't correspond to your parameters one (you can do that with jp param set
or with most SàT frontends in parameters).
example
-------
Change the XMPP password of the XMPP account of the default profile::
$ jp account modify new_password
delete
======
Delete the XMPP account linked to the given profile from the XMPP server. Before using
this command, please be sure to understand well that **THIS WILL REMOVE THE WHOLE XMPP
ACCOUNT AND DATA FROM THE XMPP SERVER**.
By default a confirmation is requested, you can do this without confirmation by using
``-f, --force``, however this is **NOT RECOMMENDED**, be sure to understand what you're
doing if you use this option (and be sure to spell correctly the profile, if you forget
the ``-p PROFILE, --profile`` argument for instance, this would delete entirely the
default profile).
.. note::
Be extra careful with this command, as it will remove the whole account from the
server, and the associated data.
example
-------
Delete the XMPP account of Pierre, which is not on the local server anymore::
$ jp account delete -p pierre

120
doc/jp/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::
$ jp ad-hoc run
If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements
to online users. This can be useful to notify an imminent maintenance of the server. Here
we notify online users that the server will be shutdown in 30 min, using a shell
substitution capabilities with a pre-registered message in the file
``~/announces/maintenance_30.txt``, then we submit it::
$ jp ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S
Get your server uptime (if supported by your server)::
$ jp ad-hoc run uptime
Run the commands available at the service with the jid ``someservice.example.org``::
$ jp ad-hoc run -s someservice.example.org
Run you server commands with verbosity so you get the name of the fields that you can fill
automatically later::
$ jp ad-hoc run -v
.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html
list
====
List ad-hoc commands available at a service.
examples
--------
List ad-hoc commands available at your server::
$ jp ad-hoc list
List ad-hoc commands available at a chat service::
$ jp ad-hoc list -j conference.example.org
remote
======
Create a remote control from launched media players. Ad-hoc commands to control the media
player will be added to your device, allowing anybody allowed (including yourself from an
other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc.
To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can
specify who is allowed to control this media player with the following options:
``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]``
jids of entities allowed to control the media player
``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]``
groups (from your roster) allowed to control you remote
``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]``
groups (from your roster) which are **NOT** allowed to control your media player
``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]``
jids of entities which are **NOT** allowed to control your media player
If you want the commands to run repeatedly (in opposition of stopping after first action
is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it.
.. note::
SàT already creates automatically a remote control if it finds a media player. This
manual way to create a remote control predate the automatic remote control, and is
currently more flexible in that you can specify who can access the remote control
(automatic remote control is only accessible by the jid of the profile).
examples
--------
Create a remote control for a running VLC instance::
$ jp ad-hoc remote vlc -l
Create a remote control for a running SMPlayer instance, and allowing anybody from your
``housemates`` group to use it::
$ jp ad-hoc remote smplayer -g housemates -l

44
doc/jp/avatar.rst Normal file
View file

@ -0,0 +1,44 @@
===============================
avatar: retrieve/upload avatars
===============================
Avatars are images associated to an XMPP entity. Several XMPP extensions are in use, SàT
tries to hide the technical details so avatar are as easy as possible to manipulate for
end-user.
get
===
Retrieve the avatar of the given entity. Entity jid is specified as positional argument.
If an avatar is found, a path to its cached file is printed. Please note that this is the
cache used by all SàT ecosystem, **do not modify the cached image**. You may use it for
read-only access, or copy it if you want to modify the image.
You may use the ``-s, --show`` argument to display the found avatar. The software used to
display the image can be specified in SàT configuration (cf. :ref:`configuration`), in the
``[jp]`` section: the ``image_cmd`` setting let you specify the path to the software. If
``image_cmd`` is not used, ``jp`` will try some common software, and if none is found, it
will try to open the image in a browser (which may sometimes result in using the default
image software of the platform).
example
-------
Get the avatar of ``louise@example.org`` and display it::
$ jp avatar get --show louise@example.org
set
===
Upload and set the given avatar for the profile. The only required argument is the path to
the image to use as avatar.
example
-------
Set the avatar of the default profile::
$ jp avatar set ~/photos/some_photo.jpg

4
doc/jp/blog.rst
View file

@ -59,6 +59,8 @@ template::
$ jp blog get -m 2 -O template --oo browser
.. _jp-blog_edit:
edit
====
@ -255,6 +257,8 @@ Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``::
$ jp blog preview ~/local/sat/blog/some_name/blog_something.md
.. _jp-blog_import:
import
======

98
doc/jp/bookmarks.rst Normal file
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::
$ jp bookmarks list
Retrieve all bookmarked URL stored in PubSub::
$ jp bookmarks list -l pubsub -t url
remove
======
Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as
positional argument. If you are deleting an URL, you need to specify it with ``-t url``
By default a confirmation is requested, use ``-f, --force`` if you don't want it (with
usual caution).
examples
--------
Delete the bookmark of a MUC room that you are not following anymore::
$ jp bookmarks remove some_old_room@conference.example.net
Delete the bookmark of a URL without requesting confirmation::
$ jp bookmarks remove -t url https://unused_url.example.net
add
===
Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as
positional argument. If you are bookmarking an URL, you need to specify it with ``-t
url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it.
For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``,
and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically
when you're connecting.
If you're using add on a jid/URL which already exists, the metadata will be updated.
examples
--------
Add a bookmark to Salut à Toi official chat room::
$ jp bookmarks add sat@chat.jabberfr.org -a
Add a link to Salut à Toi official website::
$ jp bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel"

4
doc/jp/common_arguments.rst
View file

@ -4,6 +4,8 @@ common arguments
Some arguments are used in many commands. This page describe them.
.. _jp-common_profile:
profile
=======
@ -156,6 +158,8 @@ verbose
Add a verbosity level (can be used multiple times). Use to have more concise output by
default when it makes sense.
.. _draft_common:
draft
=====

79
doc/jp/debug.rst Normal file
View file

@ -0,0 +1,79 @@
=====================================================
debug: tools to help debugging/monitoring Salut à Toi
=====================================================
``debug`` groups commands to monitor or manipulate SàT and XMPP stream.
.. _jp-debug_bridge_method:
bridge method
=============
Call a method of the bridge. You have to provide the name of the method and the arguments
as positional arguments. Arguments are evaluated as Python code (using ``eval``), so you
need to properly escape them (for your shell **and** Python). You can either split your
Python arguments as many shell arguments, or put them in a single shell argument.
You profile is automatically set if the method requires it (using the value of ``-p
PROFILE, --profile PROFILE``), so you must not specify it as an extra argument.
You can refer to `Bridge API documentation`_ to get core methods signatures
.. _Bridge API documentation: https://wiki.goffi.org/wiki/Bridge_API
examples
--------
Send a message using a single shell arguments for all Python arguments. We
use first the method name (``messageSend``), then the required arguments (see `Bridge
API documentation`_ for details), without the profile as it is automatically set. We
specify them as Python in one shell argument, so we use single quote (``\```)first for
s hell string, and inside it we use double quote (``"``) for Python strings::
$ jp debug bridge method messageSend '"louise@example.org", {"": "test message"}, {}, "auto", {}'
.. note::
This is for debugging only, if you want to send message with jp, use :ref:`jp-message_send`.
Get version string of SàT::
$ jp debug bridge method getVersion
bridge signal
=============
Send a fake signal. This is specially useful to test behaviour of a frontend when a
specific event happens. To use is you just need to specify the name of the signal and the
arguments to use (using Python eval in the same way as for jp-debug_bridge_method_).
example
-------
Send a note with ``info`` level and hand written XMLUI. Here me use a shell variable to
store the level, so we can easily change it if we want to use an other level for tests.
Note the use of quotes (to escape both for shell and Python)::
$ LEVEL='info'; jp debug bridge signal -c actionNew '{"xmlui": '"'"'<?xml version="1.0" ?><sat_xmlui title="test title" type="dialog"><dialog level="'$LEVEL'" type="note"><message>test message\non\nseveral\nlines</message></dialog></sat_xmlui>'"'"'}' '""' -1
monitor
=======
Show raw XML stream. By default, output is pretty formatted/highlighted and you get all
streams in both direction. You can filter the direction using ``-d {in,out,both},
--direction {in,out,both}``.
For this to work, you need to set the option ``Activate XML log`` in the ``Debug`` section
of your parameters.
Verbosity is used, to print details on the direction of a stanza, use ``--verbose, -v``
example
-------
Monitor raw XML stream::
$ jp debug monitor -v

126
doc/jp/encryption.rst Normal file
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::
$ jp encryption algorithms
get
===
Display which encryption session is currently active with the given entity.
The only required argument is the JID of the entity.
If not e2e encryption session exist, a message will be displayed and jp will exit with a
non zero code: this means that the messages are in clear in the XMPP servers, but normal
XMPP encryption is not affected (message should still be encrypted between client and
server and between servers).
If an e2e encryption session exist, you'll see the algorithm name and its namespace. In
case of e2e encryption which only works from device to device (e.g. it's the case with
``OTR`` which doesn't support multiple devices), you'll also see the resources of the
devices where the encryption is active in ``directed_devices``
example
-------
Check if session is encrypted with Louise::
$ jp encryption get louise@example.org
start
=====
Start e2e session with an entity.
You need to specify the JID of the entity you want to start a session with as a positional
argument.
By default, SàT will select itself the algorithm to use among those available, but you can
specify one using either its name with ``-n NAME, --name NAME`` or its namespace using
``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo``
while the namespace is the longer (e.g. ``urn:xmpp:otr:0``).
If an encryption session is started but one with an other algorithm was already there, the
original session will be stopped and replaced by one with the new requested algorithm. You
can change this behaviour by using ``--encrypt-noreplace``: in this case the command will
fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e
encryption session was already started with an other algorithm), and return a non-zero
code. If an e2e encryption session was already started with the requested algorithm, the
command will succeed in all cases an nothing will be changed.
examples
--------
Start e2e encryption with Pierre, using the algorithm selected by SàT::
$ jp encryption start louise@example.net
Start an OMEMO session with Louise::
$ jp encryption start -n omemo louise@example.org
stop
====
Terminate an e2e session with given entity. The entity must be specified as positional
argument.
After this command is run, the messages with specified entity will not be e2e encrypted
anymore (but this won't affect encryption between SàT and XMPP server and between XMPP
servers).
example
-------
Stop the e2e encryption session with Pierre::
$ jp encryption stop pierre@example.net
trust ui
========
Run the user interface to handle trust with given entity and given algorithm. The user
interface depends of 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 an other algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE,
--namespace NAMESPACE``.
.. note::
Trusting a contact or a device means that you certify that this contact or device is
the one you want to talk too. You should not trust a device if you have not verified by
an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the
fingerprint physically if possible (i.e. in front of your contact, not with computer
networks in the middle).
example
-------
Manage ``OMEMO`` trust with Louise devices::
$ jp encryption trust ui -n omemo louise@example.org

69
doc/jp/event.rst Normal file
View file

@ -0,0 +1,69 @@
========================
event: events management
========================
Event commands allows you to create/modify or get data about an event, and to manage your
invitees.
.. _jp-event_get:
get
===
Get metadata about a specific event.
example
-------
Retrieve an event metadata::
$ jp event get -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0'
.. _jp-event_create:
create
======
Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``,
and an id with ``-i ID, --id ID`` (default id is used if omitted).
Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key
can be a custom data or one of:
name
name of the event
description
details of the event
image
URL of the main picture of the event
background-image
URL of image to use as background
register
a boolean value, set to ``true`` if you want to register the event in your local list
example
-------
Create an event about to celebrate New Year::
$ jp event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg
modify
======
This command in the same way as jp-event_create_ but modify an existing event. You need to
specify the node of the event to modify using ``-n NODE, --node NODE``.
example
-------
Add a background image to the New Year event created above::
$ jp event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg
invitee
=======
Subcommands to handle guests. Please check :ref:`jp-event_invitee`.

94
doc/jp/event_invitee.rst Normal file
View file

@ -0,0 +1,94 @@
.. _jp-event_invitee:
========================================
event/invitee: event invitees management
========================================
``invitee`` groups commands to invite somebody to an event, get or set data about an invitee, and list all invitees. You can send an invitation by e-mail to people without XMPP account.
.. _jp-event_invitee_get:
get
===
Retrieve the RSVP status of one guest. Note that you must the invitees node and not the
event node. To retrieve invitees node, use :ref:`jp-event_get` with the event node.
You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare
jid will be used).
If no response is known yet, no data is returned.
example
-------
Get RSVP of Louise::
$ jp event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org
.. _jp-event_invitee_set:
set
===
Set your own RSVP data. Note that as for jp-event_invitee_get_ you must use
invitees node and not the event node.
Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of
``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value
must be an integer.
example
-------
Indicate that you'll come to an event with 3 guests::
$ jp event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3
list
====
Get and format the RSVP of your invitees. Note that as for jp-event_invitee_get_ and
jp-event_invitee_set_ you must use invitees node and not the event node.
By default, only people who have answered are shown. You may use ``-m, --missing`` to show
other people which were invited, but have not answered yet. When using this option, you
can also use ``-R, --no-rsvp`` to only show people which have not answered yet.
You'll also have a small summary indicating how many people who can expect at your event.
example
-------
Get the full list of invitees (including those who didn't answered yet) with the RSVP formatted::
$ jp event invitee list -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -m
invite
------
Invite somebody to an event. The invitation is done by e-mail, a guest account will be
created. Contrary to other ``invitee`` commands, in this one you'll use the event node
directly.
This command is really similar to :ref:`jp-invitation_create`
E-mail address is specified using ``-e EMAIL, --email EMAIL`` and you'll need to give an
URL template (using ``-U URL_TEMPLATE, --url-template URL_TEMPLATE``)leading to your
website page handling the invitation (for Libervia default invitation page is
``<your_server>/g/<uuid>``). You can use ``{uuid}`` as a placeholder which will be
replaced by event's id.
You'll probably want to specify the name of the invitee, using ``-N NAME, --name NAME``
and your own name (as the host inviting), using ``-H HOST_NAME, --host-name HOST_NAME``.
The language spoken by your guest can be specified using ``-l LANG, --lang LANG``, it is
mainly useful if you have many invitee speaking different languages.
example
-------
Pierre is inviting Louise (whose e-mail address is ``louise_email@example.net``) to an
event he's organising::
$ jp event invitee invite -e louise_email@example.et -N "Louise" -H "Pierre" -l fr -U "https://www.example.org/g/{uuid}" -u "xmpp:pierre@example.org?;node=generic%2F61400ea7-a2a2-4ce0-9b68-3735b602f671"

147
doc/jp/file.rst Normal file
View file

@ -0,0 +1,147 @@
========================================
file: files sending/receiving/management
========================================
``file`` group all commands related to file management, and allows you to send easily a
file to a contact or device from the command line.
send
====
Send a file to a contact.
The file will be sent using best available method (which is Jingle File Transfer when
available), and will try to send the file in P2P when possible. If P2P is possible, the
signal is sent through the server (metadata, negotiation, etc.), while the file itself
goes directly from the source device to the target device. When P2P is not possible, the
file may go through the server or an other one (if a proxy is used for instance).
When sending a file, you specify one or more file(s) to send, and the either the bare jid
or the full jid of the target device. If bare jid is specified, the main resource will be
used.
You'll usually want to see the progression of the transfer, use ``-P, --progress`` for
that.
If you send several files at once, you may want to use ``-b, --bz2`` to group them in a
single compressed ``tar.bz2`` archive (the client receiving the files will then receive a
single file, than the user can then decompress).
By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to
specify another one.
The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace
NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like
a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group
of files, for instance for a photo album).
examples
--------
Send a file to Louise, with a progress bar::
$ jp file send -P some_file.ext louise@example.org
Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in
the ``/some/path`` path::
$ jp file send -P -N holidays -d /some/path some_photo.jpg files.example.org
.. _jp-file_request:
request
=======
Ask to get a file from a device/sharing service. A file is requested using one or more
metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H
HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo
HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N
NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific
and not (yet?) XMPP standards.
If you already know the hash, it's the most efficient and recommended way to retrieve a
file.
You need to specify the full jid of the device or the sharing service as a positional
argument.
By default the file is downloaded in current directory, but you can specify an other one
(and an other filename) with ``-D DEST, --dest DEST``.
If you want to see progression of the transfer, use ``-P, --progress``.
examples
--------
Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service
``files.example.org``, with a progress bar::
$ jp file request -P -d photos/demo_album -n some_file.jpg files.example.org
Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't
specify it), and save it to file ``dest_file.txt``::
$ jp file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org
receive
=======
Wait for a file (or several ones) to be received, and accept it if it match criteria.
You should specify which jid you are expecting a file from, using the positional
arguments. If you don't, all files will be accepted, which can be dangerous if some
malicious user send you a file at this moment.
To see progression (this is recommended), you can use the ``-P, --progress`` options.
By default, if a file with the same name as the proposed one exists, the transfer will be
denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely
trust the sender in this case, as the name is chosen by her, and could be malicious, or it
could override an important file.
If you expect several files, you can use the ``-m, --multiple``, in this case the command
won't stop after the file received file, and you'll have to manually stop it with
``Ctrl-C`` or by sending a ``SIGTERM``.
File(s) will be written in the current directory, but you may specify an other destination
with ``--path DIR``.
examples
--------
Accept and receive the next file, save it to local directory and show a progress bar::
$ jp file receive --progress
Several files are expected from Louise, accept them and store them do
``~/Downloads/Louise``::
$ jp file receive --multiple --path ~/Downloads/Louise louise@example.org
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.
.. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload
example
-------
Upload a document to a server::
$ jp file upload -P ~/Documents/something_interesting.odt
share
=====
Subcommands for advanced file sharing. Please check :ref:`jp-file_share`.

98
doc/jp/file_share.rst Normal file
View file

@ -0,0 +1,98 @@
.. _jp-file_share:
==================================
file/share: advances files sharing
==================================
``share`` groups commands for listing file available on a device/service, sharing a file
or directory, and inviting people to retrieve files.
.. _jp-file_share_list:
list
====
List files available on a device or sharing service. You mainly have to specify the jid of
the device/service where the files are stored (if jid is omitted, your own jid will be
used, so you can check what you are sharing).
.. note::
you have to use the full jid of the device if you want to list files available on a
device.
You may specify a path using ``-d PATH, --path PATH``.
File and directories are printed with a different colour if you use default output.
examples
--------
List files shared from a device (note that we use a full jid here)::
$ jp file share list louise@example.org/some_resource
List files available on a sharing service at the path ``/photos``::
$ jp file share list -d photos files.example.org
Louise wants to list the file shared by Pierre::
$ jp file share list pierre@files.example.org
path
====
Share a local file or directory with a list of entities, or publicly. The files can then
be listed or requested using jp-file_share_list_ or :ref:`jp-file_request`.
You specify the file or directory the positional ``path`` argument. By default the name of
the file/directory is used, but you can give a different one using ``-n NAME, --name
NAME``.
You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many
time as necessary. If you don't specify any entity, the file will only be accessible by
your own devices. If you want to make your file accessible to everybody, use ``--public``
(note that this means that your file is accessible to the world, i.e. also to people you
don't know, so use this option carefully).
examples
--------
Share the file ``interesting_doc.odt`` with Pierre and Louise::
$ jp file share path -j pierre@example.net -j louise@example.org interesting_doc.odt
Imagine that you have built a weather station and want to make its data public. You can
share the directory ``~/weather_station_data`` with the world, using the name ``public
weather data``::
$ jp file share path --public --name "public weather data" ~/weather_station_data
invite
======
This command send an invitation for a file sharing repository to an XMPP entity.
The invitation is a non standard (yet?) way to notify somebody of the existence of a files
repository.
Beside the positional arguments ``service`` and ``jid``, which are respectively the
service where is the files repository and the jid of the entity to invite, you mainly have
to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and
``N NAMESPACE, --namespace NAMESPACE``.
Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a
generic files repository or a photo album.
Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL,
--thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of
the album in e.g. Libervia.
example
-------
Pierre wants to invite Louise to view his ``summer holidays`` photo album::
$ jp file share invite -P "photos/summer holidays" -t photos pierre@files.example.net
louise@example.org

102
doc/jp/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.
.. _jp-forums_get:
get
===
Get and print the structure of forums. Beside the classic PubSub node arguments, you may
specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have
several structures of forums, for instance one per language.
If you use the default output, the verbosity is used to retrieve details of topics.
examples
--------
Get structure of default forum with details::
$ jp forums get -v
Get structure of French forums in JSON::
$ jp forums get -k fr -O json
edit
====
Edit the structure of XMPP forums. As for jp-forums_get_ you may specify the key beside
the classic PubSub node arguments. The edition works the same as for :ref:`jp-blog_edit`.
To edit the structure you'll get a JSON file which is a list of object where the topic
metadata are set. You can use the following metadata:
``main-language``
a language code, using `ISO 639`_
``name``
short name of the forum
``title``
title of the topic/category in the given language
``short-desc``
small description of the topic/category
``desc``
long description of the topic/category
``uri``
URI to the PubSub node containing the messages of the topic (it's actually a blog node
with suitable permissions). URI must only be set for topic, not for categories.
``sub-forums``
list of object with the same metadata (i.e. other topics or categories)
Here is a small example of a forum structure:
.. sourcecode:: json
[
{
"main-language": "en",
"name": "short-name",
"title": "This is a category",
"short-desc": "short description about the category",
"desc": "this is a an example of a long description"
"sub-forums": [
{
"uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
"title": "some intereting topic",
"short-desc": "This is a description explaining what the topic is about"
},
{
"uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
"title": "a second topic",
"short-desc": "This topic is about bla bla bla"
},
],
},
{
"main-language": "en",
"title": "An other category",
"sub-forums": [
{
"uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
"title": "yet another topic",
"short-desc": "This is a demo topic, made for an example"
},
]
}
]
.. _ISO 639: https://www.iso.org/iso-639-language-codes.html
example
-------
Edit structure of forums on a PubSub service::
$ jp forums edit -s pubsub.example.org

34
doc/jp/identity.rst Normal file
View file

@ -0,0 +1,34 @@
=============================
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 a link to the
cached avatar.
example
--------
Get identity information about an entity::
$ jp identity get somebody@example.org
set
===
Set identity data to the server, using various XMPP extensions. You set the data to change
using ``-f KEY VALUE, --field KEY VALUE``, where ``KEY`` can only be ``nick`` at the
moment.
example
-------
Set the nickname of default profile::
$ jp identity set -f nick toto

58
doc/jp/info.rst Normal file
View file

@ -0,0 +1,58 @@
==================================
info: retrieve various information
==================================
``info`` groups subcommands used to retrieve read-only informations.
disco
=====
Display discovery information (see `XEP-0030`_ for details). This can be used to check
which features you server or a service is offering, and which items are available (items
can be services like chat room, gateways, etc).
You only have to specify the jid of the entity to check, and optionally a node.
By default both infos and items are requested, but you can restrict what to request by
using ``-t {infos,items,both}, --type {infos,items,both}``
.. _XEP-0030: https://xmpp.org/extensions/xep-0030.html
example
-------
Request infos and items from a server::
$ jp info disco example.org
version
=======
Request software version of an entity. You only need to specify the jid of the entity as
positional argument.
Depending of the software and its configuration, you have software version, software name,
and the operating system on which the software is running.
example
-------
Check version of a server::
$ jp info version example.org
session
-------
Give information about the session of the given profile. You'll the full jid currently
used on the server, and the time when the session was started (which may not be the same
time as when the connection with the XMPP server was started).
example
-------
Get session informations::
$ jp info session

119
doc/jp/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 jp commands.
To set the command, you'll write in sequence what to do with each column of your data.
For each column you can:
- specify a short option name using ``-s ARGUMENTS, --short ARGUMENTS`` (short options are
the ones with a single ``-``)
- specify a long option name using ``-l ARGUMENTS, --long ARGUMENTS`` (long options are
the ones with two ``-``)
- specify a positional argument using ``-p ARGUMENTS, --positional ARGUMENTS``
- indicate to use the column data with ``stdin`` using ``-i, --stdin``
- ignore the column if it's not used in the jp command, using ``-x, --ignore``
After each column specification, you may use a filter to manage the value. So far the
following filters are available:
``-S, --split``
This will split the value (on any whitespace character, discarding empty values) and
repeat the option which each item. This is useful when you are using an option which can
be repeated (like ``-t TAG, --tag TAG`` with ``jp blog set``).
``-E ARGUMENTS, --empty ARGUMENTS``
Indicate what to do if the column value is empty (by default en empty string is used).
You can use either ``skip`` to skip the whole row, or ``ignore`` so the option will not
be set at all (which is different from the default which will still set the option but
with an empty string).
CSV file is read from stdin, and by default unicode is expected. You may force an encoding
by using ``--encoding ENCODING``.
By default all the rows are read, but you may want to ignore first rows (if they are used
for columns title, or if you have already handled part of the list). To do that, use the
``-r ROW, --row ROW`` option.
When you test your command, it is better to do a dry run to see what will happen. The
``-D, --debug`` option is here for that: if you set it, the commands won't be actually
run, but the exact command which would be executed will be printed on screen. You should
always use this option first until you're sure that what you want will be executed.
You may add verbosity level to help debugging. With a verbosity level of 2 (i.e. ``-vv``)
the value read from CSV will be printed.
By default stdout and stderr of each launched command is ignored, but you can log them to
files using respectively ``--log LOG`` and ``--log-err LOG_ERR`` where ``LOG`` and
``LOG_ERR`` are paths to a log file to create.
Once all the sequence and options are set, you write the jp command that you want to use,
with all the needed static option (i.e. options which must be used each time).
example
-------
Louise as a spreadsheet with a table like this:
============================ ============ ============= ===============
title body internal data tags
============================ ============ ============= ===============
Some title a body ABC jp demo
Something else another body XYZ jp demo
Third one third body VWZ special_tag jp
This one doesn't have a body 123 jp demo numbers
last one last body 456 jp demo numbers
============================ ============ ============= ===============
She wants to use it as input data to create blog posts.
She first saves the file using CSV format, let's say to ``~/blog_input.csv``.
Then she checks ``jp blog set --help`` to get name of options to use. She'll need to use
``--title`` for title, ``stdin`` for the body and ``-t`` for tags. Louise wants to
activate comments, so she also wants to use ``-C`` for all posts, and a tag to says it's
coming from the spreadsheet (using ``-t spreadsheet``) .
The first row of the table is used for columns headers, so she'll start at row 1 with ``-r
1``.
There is one row without body, Louise want to skip any row without body so she'll use the
``-E skip`` filter, just after specifying the body row.
Reading column by column, the sequence is like this:
``-l title``
a title which goes to the ``--title`` long option of ``jp blog``
``-i -E skip``
a body which goes to the stdin of ``jp blog``. If the body is empty, the ``-E skip``
filter tells to skip the whole row.
``-x``
the ``internal data`` column is not used, so it is ignored
``-s t -S``
the last column are the tags, so the ``-t`` short option is used. There are several of
them separated by spaces, so the ``-S`` filter is used to split the values.
First she'll use the ``-D, --debug`` to check that the commands which will be executed are
the expected one::
$ jp input csv -D -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv
Everything seems fine, so she'll actually launch the command by running the same command
line but without the ``-D`` option::
$ jp input csv -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv
She could also have used ``--log`` and ``--log-err`` to check the logs of each command::
$ jp input csv -r 1 -l title -i -E skip -x -s t -S --log /tmp/jp_blog_stdout.log --log-err /tmp/jp_blog_stderr.log blog set -C -t spreadsheet < ~/blog_input.csv

96
doc/jp/invitation.rst Normal file
View file

@ -0,0 +1,96 @@
==============================================
invitation: invite people without XMPP account
==============================================
Invitations allows you to invite people without XMPP account, so they can participate e.g.
to a discussion by using a specially generated link. This is a Salut à Toi specific
feature and those commands are rather low lever.
.. _jp-invitation_create:
create
======
Invite somebody to participate. This will create a guest account and a link with an
identifier to access this account, and send an invitation to the given email.
The email is specified using ``-e EMAIL, --email EMAIL``, which can be used multiple times
to send the invitation to more than one address.
You'll usually want to specify the name of the person you're inviting, using ``-n NAME,
--name NAME``, it may later be used in email sent or in the web page where your guest will
land.
``-N HOST_NAME, --host-name HOST_NAME`` is used to specify the name of yourself (i.e. the
person which is inviting), it may be used in invitation message.
You'll most of time have to specify the URL template using ``-u URL, --url URL``. This
will be used in the invitation email to construct the URL where your invitee will click.
You may use the string ``{{uuid}}`` in this template which will be replaced by the id
associated to the invitation. With Libervia, default invitation page is
``<your_server>/g/<uuid>``.
The language of your guest can be specified using ``-l LANG, --lang LANG``, this is
notably useful if you have multilingual blog posts (e.g. for an event where people
speaking different languages are invited).
The ``-x KEY VALUE, --extra KEY VALUE`` is used for extra data which depend on what you
are inviting your guests for.
example
-------
Invite Louise, which is speaking French, to an event. The invitation is sent to her email
address ``louise_email@example.net``, is sent by Piotr, and must link to the Libervia
instance at ``https://www.example.org/g/<id>``. We use here the ``event_uri`` extra key::
$ jp invitation create -n Louise -N Pierre -e louise_email@example.net -l fr -u "https://www.example.org/g/{uuid}" -x event_uri xmpp:pierre@example.org?;node=MnXe4ic2X8RUz6JAJuw4f9;item=org.salut-a-toi.event%3A0
get
===
Get metadata for one specific invitation. You only have to specify the invitation id, and
you may use the option ``-j, --with-jid`` to also get the jid used for the invitation
(this will start the session of the invitee).
example
-------
Get invitation data for invitation with id ``okFec4gDz75My7iQAVTmsc``::
$ jp invitation get okFec4gDz75My7iQAVTmsc -j
modify
======
This work the same way as jp-invitation_create_, you only have to specify the ``id`` of the
invitation.
If you use the ``--replace`` argument, all the invitation data will be replaced by the
ones you're specifying.
example
-------
Change the language of the invitee for the invitation ``okFec4gDz75My7iQAVTmsc`` for
Slovak::
$ jp invitation modify -l sk okFec4gDz75My7iQAVTmsc
list
====
List registered invitations. You may filter by the profile who made the invitation using
``-p PROFILE, --profile PROFILE``.
The invitations are shown by default using id as main data, and metadata below.
example
-------
List invitations::
$ jp invitation list

81
doc/jp/merge-request.rst Normal file
View file

@ -0,0 +1,81 @@
===============================================
merge-request: create and manage merge requests
===============================================
Merge-request are used to propose some modifications to a project. They are generic and
are made to be used with several backends, but only Mercurial is implemented so far.
To prepare a merge request with Mercurial, you just need to have a clone of the project,
and do your modifications (either directly, or in a bookmark, a branch, or a MQ patch).
set
===
Create and publish a merge request. Once the modification on the project are done, simply
run the command from the repository (or specify its path with ``-r PATH, --repository
PATH``). If the project has set metadata (it can be done with a magic string in README),
you don't have to specify any service or node, it will be set automatically (but you still
can specify them if needed).
You may associate one or more labels to your request using ``-l LABELS, --label LABELS``.
By default, a confirmation is requested before publishing the request, you can publish
without confirmation by using the ``-f, --force`` flag.
If you have already done a merge request and you just want to update it, check its id and
specify it with ``-i ITEM, --item ITEM``, this will override the previous request with the
new updated one.
examples
--------
Publish a merge request (to be executed from the repository of the project you have
modified)::
$ jp merge-request set
Update an existing merge request, which has the id ``123`` (to be executed from the
reposiroty of the project you have modified)::
$ jp merge-request set -i 123
Do a merge request for repository at path ``~/some_project``, specifying a label
indicating it's work in progress (WIP)::
$ jp merge-request set -r ~/some_project --label WIP
get
===
Get and print one or more merge requests. By default only some metadata are shown (without
the patches), but you can use ``--verbose, -v`` to show details.
examples
--------
Show some metadata of last 5 merge requests::
$ jp merge-request get -M 5
Display details for merge request with id 456::
$ jp merge-request get -v -i 456
import
======
Import a merge request into your project. You mainly have to be in the project repository
(or specify it using ``-r PATH, --repository PATH``) and to specify the id of the patch to
import (using ``-i ITEM, --item ITEM``). The behaviour depends of the type of the patch,
for Mercurial, the patch will be imported as `MQ`_ patch.
.. _MQ: https://www.mercurial-scm.org/wiki/MqExtension
example
-------
Import the merge request with id 321::
$ jp merge-request import -i 321

6
doc/jp/message.rst
View file

@ -6,10 +6,12 @@ message: chat message management
Message commands let you send chat messages or manage your server message archives.
.. _jp-message_send:
send
====
send a message to a contact or a chat room.
Send a message to a contact or a chat room.
``stdin`` is used as message source.
You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed.
You can manage your encrypted session using ``encryption`` command.
@ -36,7 +38,7 @@ Send a ``normal`` message marked as French with a subject::
mam
===
query archives using MAM.
Query archives using MAM.
This command allows you to check message archive kept on the server (i.e. not the local copy).
You usually want to specify a starting point, and a number of message to retrieve. If too many messages
are available, you'll have to use RSM commands to navigate through the results.

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