.. _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 Libervia/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]
                          [-t {chat,error,groupchat,headline,normal,auto}]
                          [-e ALGORITHM] [--encrypt-noreplace] […]
                          jid

   positional arguments:
     jid                   the destination jid

   options:
     -h, --help            show this help message and exit
     -p, --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
     -t, --type {chat,error,groupchat,headline,normal,auto}
                           type of the message
     -e, --encrypt ALGORITHM
                           encrypt message using given algorithm
     --encrypt-noreplace   don't replace encryption algorithm if another one is
                           already used
     […]

The output above has been shortened: use ``--help`` to see the full list of options.

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).

.. _li_isolation:

Isolation
---------

Several Libervia instances can run side by side, each with its own data, this is called
isolation (see :ref:`configuration_isolation` for details). The instance to work with is
selected with the ``-i/--isolation NAME`` option, which must be used before the command:

.. code-block:: console

   $ li -i pubsub profile list

.. note::

   If the ``LIBERVIA_ISOLATION`` environment variable is already set, this option is not
   needed, unless you want to work with another instance (the option takes priority over
   the environment variable).

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