# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1655473815 -7200
# Node ID adebd8036b68d0e2404780856d6c081d3448db60
# Parent  33ab258df0de3193c45596cdb2a6bbcada25e4ba
doc (cli/message): `retract` command

diff -r 33ab258df0de -r adebd8036b68 doc/libervia-cli/message.rst
--- a/doc/libervia-cli/message.rst	Fri Jun 17 14:15:23 2022 +0200
+++ b/doc/libervia-cli/message.rst	Fri Jun 17 15:50:15 2022 +0200
@@ -35,10 +35,47 @@
 
   $ echo 'Bonjour, je vous écris avec « Libervia »' | li message send -l fr -t normal -S 'Ceci est un message de test'
 
+retract
+=======
+
+Retract a message, i.e. mark it as retracted in database, and send a retraction request to
+original recipient.
+
+When a message is marked as retracted in database, it won't appear anymore or a hint
+(commonly called *tombstone*) will be displayed instead (the behaviour depend of the
+frontend that you're using). However, there is an option to archive retracted messages:
+``Privacy``/``retract_history``. This option is disabled by default, but if you set it
+(e.g. with ``li param set``), the original message will be kept in metadata and may be
+displayed if the frontend that you're using allows it.
+
+The ``message_id`` positional argument is the internal ID of the message (not an XMPP ID).
+It may be displayed by some frontends.
+
+.. note::
+
+   It is not possible to be sure that a message will be retracted: once something is sent
+   through the network, any recipient can keep it, copy it, share it, etc. This is true for
+   Libervia/XMPP as for any software, decentralized or not.
+
+   Retract send a retractation **request**, i.e. it asks to the recipient(s) client(s) to
+   hide or delete the message, but it's not possible to have a guarantee that nobody kept
+   a request.
+
+   The message is also removed from database, except if the option
+   ``Privacy``/``retract_history`` is set (see above).
+
+example
+-------
+
+Retract message with ID ``1234-5678-9abc-def0``::
+
+  $ li message retract 1234-5678-9abc-def0
+
 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.