==================================
contacts: handle contacts metadata
==================================

Contacts use the `End-to-End Encrypted Contacts Metadata`_ to handle contact metadata.
This is a new mechanism that complements the XMPP native “Roster” mechanism. The
advantages are that contacts can be optionally end-to-end encrypted, preventing metadata
from being accessible to the server, and that additional metadata can be associated with
contacts and groups. The disadvantages are that most clients do not support it, so your
contacts may not appear in them. Also, the server may need to access your contacts list to
make decisions, for instance, to filter undesirable messages, which is not possible with
end-to-end encrypted contacts (and no server currently supports pubsub contacts).

This feature is experimental and designed to reduce XMPP metadata exposure. For backward
compatibility, use :ref:`li_roster` (note that the native roster cannot be end-to-end
encrypted).

.. _End-to-End Encrypted Contacts Metadata: https://xmpp.org/extensions/inbox/contacts-e2e.html

get
===

Retrieve the current contacts and their associated groups. By default, they are displayed
in a table showing all metadata, along with an indicator of whether they are end-to-end
encrypted.

Groups are displayed with their name, ID, and description (if available).

examples
--------

Retrieve all contacts and their associated groups::

  $ li contacts get

set
===

Add or replace a contact. By default, the contact metadata will be end-to-end encrypted,
but you can store it in plaintext by using the ``--no-encrypt`` flag.

You can specify contact groups by ID (using ``-G, --group-ids GROUP_ID``) or by name
(using ``-g, --group-names GROUP_NAME``). Both options can be provided multiple times.

examples
--------

Add Louise as a new contact::

  $ li contacts set -n Louise louise@example.org -g friends -g school
