annotate doc/libervia-cli/message.rst @ 4219:1b5cf2ee1d86

plugin XEP-0384, XEP-0391: download missing devices list: when a peer jid was not in our roster, devices list was not retrieved, resulting in failed en/decryption. This patch does check it and download missing devices list in necessary. There is no subscription managed yet, so the list won't be updated in case of new devices, this should be addressed at some point.
author Goffi <goffi@goffi.org>
date Tue, 05 Mar 2024 17:31:36 +0100
parents d6837db456fd
children 073bb1d1a7f8
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
4077
d6837db456fd refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 3806
diff changeset
92 $ li message mam -S "5 hours ago" -s libervia@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
4077
d6837db456fd refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents: 3806
diff changeset
96 $ li message mam -S 2019-01-01 -s libervia@chat.jabberfr.org -m 2