Mercurial > libervia-backend
annotate doc/libervia-cli/message.rst @ 4326:5fd6a4dc2122
cli (output/std): use `rich` to output JSON.
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 20 Nov 2024 11:38:44 +0100 |
| parents | 073bb1d1a7f8 |
| children |
| rev | line source |
|---|---|
| 2946 | 1 .. highlight:: sh |
| 2 | |
| 3 ================================ | |
| 4 message: chat message management | |
| 5 ================================ | |
| 6 | |
| 7 Message commands let you send chat messages or manage your server message archives. | |
| 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 | 11 send |
| 12 ==== | |
| 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 | 15 ``stdin`` is used as message source. |
| 16 You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed. | |
| 17 You can manage your encrypted session using ``encryption`` command. | |
| 18 | |
|
4311
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
19 It's possible to send a message to several participants at once (besides group chat), |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
20 using addressing commands like ``--to``, ``--cc``, or ``--bcc``. This works in a similar |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
21 way as for emails. If your server supports it (i.e., if it supports `XEP-0033`_), only |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
22 one message will be sent from Libervia, and the server will handle the rest. If it doesn't |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
23 support multicasting, Libervia will handle it itself and send as many messages as |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
24 necessary. |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
25 |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
26 You can also add metadata to the message to indicate who must get the reply (with |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
27 ``--reply-to`` and ``reply-room``) or if the message doesn't expect any reply (with |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
28 ``--no-reply``). |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
29 |
| 2946 | 30 examples |
| 31 -------- | |
| 32 | |
| 33 Send a message to a contact:: | |
| 34 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3454
diff
changeset
|
35 $ echo 'Salut à Toi!' | li message send louise@example.net |
| 2946 | 36 |
| 37 Send a message encrypted with OMEMO:: | |
| 38 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3454
diff
changeset
|
39 $ echo 'pssst, this message is encrypted' | li message send -e omemo louise@example.net |
| 2946 | 40 |
| 41 Send a ``normal`` message marked as French with a subject:: | |
| 42 | |
| 3505 | 43 $ echo 'Bonjour, je vous écris avec « Libervia »' | li message send -l fr -t normal -S 'Ceci est un message de test' |
| 2946 | 44 |
|
3806
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
45 retract |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
46 ======= |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
47 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
48 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
|
49 original recipient. |
|
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 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
|
52 (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
|
53 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
|
54 ``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
|
55 (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
|
56 displayed if the frontend that you're using allows it. |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
57 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
58 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
|
59 It may be displayed by some frontends. |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
60 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
61 .. note:: |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
62 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
63 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
|
64 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
|
65 Libervia/XMPP as for any software, decentralized or not. |
|
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 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
|
68 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
|
69 a request. |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
70 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
71 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
|
72 ``Privacy``/``retract_history`` is set (see above). |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
73 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
74 example |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
75 ------- |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
76 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
77 Retract message with ID ``1234-5678-9abc-def0``:: |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
78 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
79 $ li message retract 1234-5678-9abc-def0 |
|
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
80 |
| 2946 | 81 mam |
| 82 === | |
| 83 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
84 Query archives using MAM. |
|
3806
adebd8036b68
doc (cli/message): `retract` command
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
85 |
| 2946 | 86 This command allows you to check message archive kept on the server (i.e. not the local copy). |
| 87 You usually want to specify a starting point, and a number of message to retrieve. If too many messages | |
| 88 are available, you'll have to use RSM commands to navigate through the results. | |
| 89 | |
| 90 examples | |
| 91 -------- | |
| 92 | |
| 93 Retrieve messages from last 2 days:: | |
| 94 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3454
diff
changeset
|
95 $ li message mam -S "2 days ago" |
| 2946 | 96 |
|
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
97 Retrieve messages from last 5 hours on Libervia official chat room:: |
| 2946 | 98 |
|
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
3806
diff
changeset
|
99 $ li message mam -S "5 hours ago" -s libervia@chat.jabberfr.org |
| 2946 | 100 |
|
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3505
diff
changeset
|
101 Retrieve 2 first messages of 2019 on Libervia official chat room:: |
| 2946 | 102 |
|
4077
d6837db456fd
refactoring: fix names in doc following modules hierarchy refactoring
Goffi <goffi@goffi.org>
parents:
3806
diff
changeset
|
103 $ li message mam -S 2019-01-01 -s libervia@chat.jabberfr.org -m 2 |
|
4311
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
104 |
|
073bb1d1a7f8
doc (cli/message): add documentation for new addressing commands:
Goffi <goffi@goffi.org>
parents:
4077
diff
changeset
|
105 .. _XEP-0033: https://xmpp.org/extensions/xep-0033.html |