Mercurial > libervia-backend

annotate doc/libervia-cli/message.rst @ 3806:adebd8036b68

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (cli/message): `retract` command
author Goffi <goffi@goffi.org>
date Fri, 17 Jun 2022 15:50:15 +0200
parents 267e4987b58b
children d6837db456fd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. highlight:: sh
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ================================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 message: chat message management
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ================================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Message commands let you send chat messages or manage your server message archives.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
8
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
9 .. _libervia-cli_message_send:
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents: 2946
diff changeset
10
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
11 send
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 ====
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
13
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents: 2946
diff changeset
14 Send a message to a contact or a chat room.
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 ``stdin`` is used as message source.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
16 You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 You can manage your encrypted session using ``encryption`` command.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
18
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 examples
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
20 --------
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
21
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 Send a message to a contact::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
23
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
24 $ echo 'Salut à Toi!' | li message send louise@example.net
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 Send a message encrypted with OMEMO::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
28 $ echo 'pssst, this message is encrypted' | li message send -e omemo louise@example.net
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
29
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
30 .. note::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
31
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 Fingerprints of your destinee must have been accepted before using OMEMO, else message can't be encrypted
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
33
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 Send a ``normal`` message marked as French with a subject::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
35
3505
4705f80b6e23 doc: more renaming
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
36 $ echo 'Bonjour, je vous écris avec « Libervia »' | li message send -l fr -t normal -S 'Ceci est un message de test'
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
37
3806
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
38 retract
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
39 =======
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
40
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
41 Retract a message, i.e. mark it as retracted in database, and send a retraction request to
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
42 original recipient.
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
43
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
44 When a message is marked as retracted in database, it won't appear anymore or a hint
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
45 (commonly called *tombstone*) will be displayed instead (the behaviour depend of the
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
46 frontend that you're using). However, there is an option to archive retracted messages:
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
47 ``Privacy``/``retract_history``. This option is disabled by default, but if you set it
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
48 (e.g. with ``li param set``), the original message will be kept in metadata and may be
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
49 displayed if the frontend that you're using allows it.
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
50
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
51 The ``message_id`` positional argument is the internal ID of the message (not an XMPP ID).
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
52 It may be displayed by some frontends.
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
53
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
54 .. note::
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
55
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
56 It is not possible to be sure that a message will be retracted: once something is sent
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
57 through the network, any recipient can keep it, copy it, share it, etc. This is true for
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
58 Libervia/XMPP as for any software, decentralized or not.
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
59
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
60 Retract send a retractation **request**, i.e. it asks to the recipient(s) client(s) to
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
61 hide or delete the message, but it's not possible to have a guarantee that nobody kept
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
62 a request.
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
63
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
64 The message is also removed from database, except if the option
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
65 ``Privacy``/``retract_history`` is set (see above).
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
66
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
67 example
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
68 -------
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
69
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
70 Retract message with ID ``1234-5678-9abc-def0``::
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
71
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
72 $ li message retract 1234-5678-9abc-def0
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
73
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 mam
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
75 ===
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
76
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents: 2946
diff changeset
77 Query archives using MAM.
3806
adebd8036b68 doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
78
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 This command allows you to check message archive kept on the server (i.e. not the local copy).
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 You usually want to specify a starting point, and a number of message to retrieve. If too many messages
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
81 are available, you'll have to use RSM commands to navigate through the results.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
83 examples
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 --------
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
85
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 Retrieve messages from last 2 days::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
88 $ li message mam -S "2 days ago"
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
89
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
90 Retrieve messages from last 5 hours on Libervia official chat room::
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
91
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
92 $ li message mam -S "5 hours ago" -s sat@chat.jabberfr.org
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
94 Retrieve 2 first messages of 2019 on Libervia official chat room::
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3454
diff changeset
96 $ li message mam -S 2019-01-01 -s sat@chat.jabberfr.org -m 2