Mercurial > libervia-backend

annotate doc/libervia-cli/roster.rst @ 4326:5fd6a4dc2122

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cli (output/std): use `rich` to output JSON.
author Goffi <goffi@goffi.org>
date Wed, 20 Nov 2024 11:38:44 +0100
parents 267e4987b58b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 ================================
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
2 roster: manager an entity roster
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ================================
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
4
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 "Roster" is the name used in XMPP for the contact list. In addition to list of contacts,
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
6 you have also data like subscription information or groups associated to a contact.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
7
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 Groups are simple strings associated to one or more contacts (e.g. "friends" or "family").
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 Subscription is the mechanism to get presence information of an entity. When you add a
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
11 contact to your roster, most XMPP clients also do a presence subscription request, than
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 the entity may accept or deny. If a presence subscription is accepted, the subscribed user
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 can see when the other entity is online, and its presence status.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
14
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 get
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
16 ===
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
17
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 Show the current roster. By default only a display name and JIDs are displayed, but you
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 can increase verbosity to also display groups, or all other metadata.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
21 The short name shown next to jid is either the ``name`` specified in roster, or the node
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 part of the jid. If none of them exist, only the entity JID is shown.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
23
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 The following metadata may be displayed:
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 groups
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
27 group the entity belong too
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 ask
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 true if a presence subscription request has been sent (but not answered yet)
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
30 from
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 the contact has a subscription to user presence (i.e. your contact can see when you're
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 online and your presence status)
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
33 to
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 the user has a subscription to the contact presence (i.e. you can see when you're
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 contact is online and his/her presence status)
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
36
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 examples
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 --------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 Get roster of default profile and display groups::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
41
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
42 $ li roster get -v
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 Get roster of default profile and display all metadata::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
45
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
46 $ li roster get -vv
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
47
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 Get roster or default profile and show the result in JSON::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
49
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
50 $ li roster get -O json
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
51
3255
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
52 set
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
53 ===
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
54
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
55 Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
56 the user chosed name to use with a contact.
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
57
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
58 By default, values are appended, i.e. if ``name`` is not set it won't delete existing one,
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
59 and ``groups`` are appended to existing one. However, if you use the ``-R, --replace``
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
60 option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
61 NAME, --name NAME`` option, the former one will be deleted, and any former group no added
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
62 using ``-g GROUP, --group GROUP`` will be removed).
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
63
3283
7b58b15bd121 doc (jp/roster): fixed example for `jp roster set`
Goffi <goffi@goffi.org>
parents: 3255
diff changeset
64 examples
7b58b15bd121 doc (jp/roster): fixed example for `jp roster set`
Goffi <goffi@goffi.org>
parents: 3255
diff changeset
65 --------
3255
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
66
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
67 Set a name used to privately identify your contact Louise::
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
68
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
69 $ li roster set -n Enjolras louise@example.net
3255
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
70
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
71 Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``::
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
72
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
73 $ li roster set --replace -g friends -g housemates pierre@example.net
3255
012e89fb2dd1 jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
74
3414
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
75 delete
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
76 ======
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
77
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
78 Remove an entity from roster.
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
79
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
80 examples
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
81 --------
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
82
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
83 Remove John from your roster::
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
84
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
85 $ li roster delete john@example.net
3414
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
86
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
87 stats
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 =====
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
89
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
90 Show some statistics about the profile roster. The number of contacts per server is shown,
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 with a percentage of contacts on this server compared to the total number of contacts.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 This can notably be helpful to see if there is a concentration of your contacts in a
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
93 specific server or gateway.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
94
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
95 Other more or less useful numbers are shown, they are self explaining.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
96
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
98 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
99
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 Get statistic for the default profile::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
101
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
102 $ li roster stats
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 purge
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 =====
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 This command is used to remove from the roster all contacts which have no subscription or
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
108 only partial subscription.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
109
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
110 By default, only contacts without subscription at all are removed. With ``--no-from`` you
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
111 also remove contacts which have no subscription to you (but you have a subscription to
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
112 them), and with ``--no-to`` you also remove contacts that you are not subscribed to (but
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
113 who are subscribed to you).
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
114
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
116 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
117
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
118 Remove all contacts from default profile which have no subscription at all or from which
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
119 the default profile is not subscribed to::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
120
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
121 $ li roster purge --no-to
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 resync
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 ======
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
125
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
126 Libervia uses `roster versioning`_ to optimize the synchronisation of roster with server on
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 client connection. This means that once the roster has been retrieved, on each following
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
128 connection, only the difference of contacts (i.e. which new or removed contacts) is
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 received.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
130
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
131 This command does a full resynchronisation of the roster, or in other words it requests
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 the whole roster and save it, replacing the list built with versioning. ``resync`` is
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 mostly useful for developers and end-user should not need this command, as roster
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
134 versioning is supposed to work fine and the roster should be synchronised correctly on
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
135 startup. But if for any reason you suspect that your current roster list is corrupted, you
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 may use it to be sure that a full resynchronisation is done.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 .. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
139
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 exemple
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
141 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
142
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 Do a full resynchronisation of default profile's roster::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
144
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
145 $ li roster resync