Mercurial > libervia-backend

comparison doc/libervia-cli/common_arguments.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/common_arguments.rst@d2a26ec74b31
children 6d03e8ebf1a6
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 ================
2 common arguments
3 ================
4
5 Some arguments are used in many commands. This page describe them.
6
7 .. _libervia-cli_common_profile:
8
9 profile
10 =======
11
12 profile arguments are really common, they allow you to select your profile.
13 If you don't select any, the default profile is used, which is the first
14 profile created or the one you have explicitly set. You can check which profile
15 is used by default with ``li profile default``.
16
17 The common arguments for profile are:
18
19 ``-p PROFILE, --profile PROFILE``
20 to select the name of your profile. It can be a profile key like ``@DEFAULT@``
21
22 ``-c, --connect``
23 connect the profile to the XMPP server before doing anything else. If your
24 profile is already connected, nothing happen. This is specially useful in scripts.
25
26 ``--start-session``
27 starts a session without connecting, this can be needed if you can't connect but
28 you need to access your session e.g. to change parameters.
29 This is advanced used and is not need in most common cases.
30
31 ``--pwd PASSWORD``
32 the password of your profile, needed if the session is not started yet.
33
34 .. note::
35
36 using the ``--pwd`` option is not secure if you are not the only user of your machine:
37 the password will appear **IN CLEAR** in the list of launched processes, or in the
38 history of your shell. If the profile password is needed and not specified, it will be
39 prompted (with echo disabled). If you are on a shared machine or if anybody can access
40 your shell history at some point, you should either connect first your profile with an
41 other frontend (Primitivus for instance), or avoid the ``--pwd`` option and use the
42 prompt instead.
43
44 .. _pubsub_common:
45
46 pubsub
47 ======
48
49 pubsub arguments are used in many commands, they allow you to select a service, node and
50 items. Depending on the command, you may only not be able to select an item, or you may
51 select one or multiple items.
52
53 The common arguments for pubsub are:
54
55 ``-u PUBSUB_URL, --pubsub-url PUBSUB_URL``
56 retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an
57 ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to
58 retrieve the location of the XMPP node/item, if available.
59 Note that you can override parts of the location in the URL if you specify service, node
60 or item.
61
62 e.g.::
63
64 $ li blog get -u https://www.goffi.org
65
66 ``-s SERVICE, --service``
67 used to specifiy the JID of the pubsub service
68
69 ``-n NODE, --node NODE``
70 used to specifiy the pubsub node
71
72 ``-i ITEM, --item ITEM``
73 for commands where an item can be specified, you do it with this option. In some
74 commands, multiple items can be specified, in this case just use this arguments several
75 times.
76
77 ``-L, --last-item``
78 when an item id is needed, you can use this option to retrieve the last published item.
79 e.g.::
80
81 $ li blog edit --last-item
82
83 ``-M, --max-items``
84 use to specify a maxium number of items to retrieve, when it makes sense.
85 Note that this is using the pubsub max (i.e. defined in
86 `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should
87 implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in
88 this case the ``-m, --max`` argument should be prefered. See below for RSM common
89 arguments.
90
91 result set management
92 =====================
93
94 Result Set Management (RSM) common arguments are used to navigate into pages of results
95 when lot of elements may be expected. Given a result with a large number of arguments, a
96 *page* is set of elements which correspond to an *index* (a page number). For instance if
97 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to
98 20 included.
99
100
101 ``-a ITEM_ID, --after ITEM_ID``
102 find page after this item. You usually use the last item id of the latest page you got.
103
104 ``-b ITEM_ID, --before ITEM_ID``
105 find page before this item. This this usually used when you check items backwards
106
107 ``--index RSM_INDEX``
108 index of the page to retrieve. Note that first page has index **0**.
109
110 ``-m RSM_MAX, --max RSM_MAX``
111 used to specify a maxium number of items to retrieve per page. Note that the actual
112 maximum number of items per page used may be lower if the service used consider that
113 your request is too big.
114
115 message archive management
116 ==========================
117
118 Message Archive Management (MAM) argument is used by some commands (related to instant message or
119 pubsub) to filter results.
120
121 There is currently only one argument in this group:
122
123 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE``
124 specify a MAM filter to use. Depending on the service supporting MAM, some filters can
125 be used to do things like full text search. The available filters depend on the service
126 you use, please check documentation of your service.
127
128 order-by
129 ========
130
131 Order-By argument specify how the returned elements are sorted.
132
133 There is currently only one argument in this group:
134
135 ``-o {creation,modification}, --order-by {creation,modification}``
136 specify how result is sorted. with ``creation``, first created element is returned
137 first. There is no notion of *creation* of *modification* in original
138 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an
139 existing id will overwrite the older one, creating a new item. With this option, we use
140 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and
141 *creation* time is the time when the first item has been published, before being
142 overwritten.
143
144 In the case of ``modification``, if an item is overwritten, it reappears on top, this is
145 the default pubsub sorting order.
146
147 progress
148 ========
149
150 This single option may be used when a long operation is happening, like a file transfer.
151
152 ``-P, --progress``
153 Show progress bar.
154
155 verbose
156 =======
157
158 ``--verbose, -v``
159 Add a verbosity level (can be used multiple times). Use to have more concise output by
160 default when it makes sense.
161
162 .. _draft_common:
163
164 draft
165 =====
166
167 Common arguments used when an edition is potentially long to do, and a file may be kept
168 until publication.
169
170
171 ``-D, --current``
172 Used when you have started to edit something (e.g. a blog post), which is not yet
173 published, and you want to continue your work.
174
175 e.g.::
176
177 $ li blog edit -D
178
179 ``-F DRAFT_PATH, --draft-path DRAFT_PATH``
180 Used when you have started to edit something and want to continue your work from this
181 file. In other words, it's similar to ``-D, --current`` except that you specify the file
182 to use instead of using the last available draft.
183
184 .. _libervia-cli_output:
185
186 output
187 ======
188
189 Output is used when you want to get the result of the command in a specific way. It may be
190 used, for instance, to retrieve the result formatted in JSON so the data can be easily
191 manipulated by a script, or if you want only a specific element of the result.
192
193 ``-O {…}, --output {…}``
194 specifiy the output to use. Available options depends of the command you are using,
195 check ``li [your command] --help`` to know them.
196
197 e.g.::
198
199 $ li blog get -O json
200
201 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS``
202 depending of the output selected, you may have options to customise the output.
203 For instance, if you use the ``template`` output, you may use an option to display the
204 result in a browser.
205
206 e.g.::
207
208 $ li blog
209
210 Some options expect parameters, in this case they can be specified using ``=``.
211
212 e.g. specifiying a template to use::
213
214 $ li blog get -O template --oo browser --oo template=/tmp/my_template.html