--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/ad-hoc.rst	Sun Mar 21 18:23:58 2021 +0100
@@ -0,0 +1,120 @@
+=======================
+ad-hoc: Ad-Hoc commands
+=======================
+
+Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used
+either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get
+list of connected users, send a service announcement, restart parts of the server), or
+execute about anything (e.g. control a physical robot with XMPP).
+
+run
+===
+
+Run an ad-hoc command. You may specify the node to run as positional argument, or let it
+empty to list available commands.
+
+By default the commands from your server are used, but with ``-j JID, --jid JID`` you can
+specify a different entity.
+
+You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and
+``-S, --submit`` as many time as needed.  ``--field`` expect a ``KEY`` which is the name
+of the field to set. If you don't know which name to use, you can run the command to
+automatise a first time manually with ``--verbose, -v`` flag, this will display fields
+names when you have to fill them.
+
+Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then
+if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and
+so on as many times as you need.
+
+Don't forget that you can use your shell substitution capabilities if necessary, for
+instance if you have a pre-registered announce to send.
+
+examples
+--------
+
+Get a list of available commands on your server to launch a command::
+
+  $ li ad-hoc run
+
+If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements
+to online users. This can be useful to notify an imminent maintenance of the server. Here
+we notify online users that the server will be shutdown in 30 min, using a shell
+substitution capabilities with a pre-registered message in the file
+``~/announces/maintenance_30.txt``, then we submit it::
+
+  $ li ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S
+
+Get your server uptime (if supported by your server)::
+
+  $ li ad-hoc run uptime
+
+Run the commands available at the service with the jid ``someservice.example.org``::
+
+  $ li ad-hoc run -s someservice.example.org
+
+Run you server commands with verbosity so you get the name of the fields that you can fill
+automatically later::
+
+  $ li ad-hoc run -v
+
+.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html
+
+list
+====
+
+List ad-hoc commands available at a service.
+
+examples
+--------
+
+List ad-hoc commands available at your server::
+
+  $ li ad-hoc list
+
+List ad-hoc commands available at a chat service::
+
+  $ li ad-hoc list -j conference.example.org
+
+remote
+======
+
+Create a remote control from launched media players. Ad-hoc commands to control the media
+player will be added to your device, allowing anybody allowed (including yourself from an
+other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc.
+
+To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can
+specify who is allowed to control this media player with the following options:
+
+``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]``
+  jids of entities allowed to control the media player
+
+``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]``
+  groups (from your roster) allowed to control you remote
+
+``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]``
+  groups (from your roster) which are **NOT** allowed to control your media player
+
+``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]``
+  jids of entities which are **NOT** allowed to control your media player
+
+If you want the commands to run repeatedly (in opposition of stopping after first action
+is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it.
+
+.. note::
+
+   SàT already creates automatically a remote control if it finds a media player. This
+   manual way to create a remote control predate the automatic remote control, and is
+   currently more flexible in that you can specify who can access the remote control
+   (automatic remote control is only accessible by the jid of the profile).
+
+examples
+--------
+
+Create a remote control for a running VLC instance::
+
+  $ li ad-hoc remote vlc -l
+
+Create a remote control for a running SMPlayer instance, and allowing anybody from your
+``housemates`` group to use it::
+
+  $ li ad-hoc remote smplayer -g housemates -l