Mercurial > libervia-backend
annotate doc/libervia-cli/common_arguments.rst @ 4175:30f7513e5590
plugin XEP-0277: generate and parse altertate links with the new `alt_links` data in `extra`
author | Goffi <goffi@goffi.org> |
---|---|
date | Tue, 05 Dec 2023 13:14:03 +0100 |
parents | d0b66efc6c0e |
children |
rev | line source |
---|---|
2946 | 1 ================ |
2 common arguments | |
3 ================ | |
4 | |
5 Some arguments are used in many commands. This page describe them. | |
6 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
7 .. _libervia-cli_common_profile: |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
8 |
2946 | 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 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
15 is used by default with ``li profile default``. |
2946 | 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 | |
3050
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
36 using the ``--pwd`` option is not secure if you are not the only user of your machine: |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
37 the password will appear **IN CLEAR** in the list of launched processes, or in the |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
38 history of your shell. If the profile password is needed and not specified, it will be |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
39 prompted (with echo disabled). If you are on a shared machine or if anybody can access |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
40 your shell history at some point, you should either connect first your profile with an |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
41 other frontend (Primitivus for instance), or avoid the ``--pwd`` option and use the |
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
42 prompt instead. |
2946 | 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 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
64 $ li blog get -u https://www.goffi.org |
2946 | 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 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
81 $ li blog edit --last-item |
2946 | 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 | |
3608
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
91 ``-C, --no-cache`` |
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
92 skip pubsub cache. By default, internal pubsub cache is used automatically if requested |
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
93 items are available there. With this option set, a request to the pubsub service will |
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
94 always be done, regardless of presence of node items in internal cache. |
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
95 |
2946 | 96 result set management |
97 ===================== | |
98 | |
99 Result Set Management (RSM) common arguments are used to navigate into pages of results | |
100 when lot of elements may be expected. Given a result with a large number of arguments, a | |
101 *page* is set of elements which correspond to an *index* (a page number). For instance if | |
102 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to | |
103 20 included. | |
104 | |
105 | |
106 ``-a ITEM_ID, --after ITEM_ID`` | |
107 find page after this item. You usually use the last item id of the latest page you got. | |
108 | |
109 ``-b ITEM_ID, --before ITEM_ID`` | |
110 find page before this item. This this usually used when you check items backwards | |
111 | |
112 ``--index RSM_INDEX`` | |
113 index of the page to retrieve. Note that first page has index **0**. | |
114 | |
115 ``-m RSM_MAX, --max RSM_MAX`` | |
116 used to specify a maxium number of items to retrieve per page. Note that the actual | |
117 maximum number of items per page used may be lower if the service used consider that | |
118 your request is too big. | |
119 | |
120 message archive management | |
121 ========================== | |
122 | |
123 Message Archive Management (MAM) argument is used by some commands (related to instant message or | |
124 pubsub) to filter results. | |
125 | |
126 There is currently only one argument in this group: | |
127 | |
128 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` | |
129 specify a MAM filter to use. Depending on the service supporting MAM, some filters can | |
130 be used to do things like full text search. The available filters depend on the service | |
131 you use, please check documentation of your service. | |
132 | |
133 order-by | |
134 ======== | |
135 | |
2957 | 136 Order-By argument specify how the returned elements are sorted. |
2946 | 137 |
138 There is currently only one argument in this group: | |
139 | |
140 ``-o {creation,modification}, --order-by {creation,modification}`` | |
141 specify how result is sorted. with ``creation``, first created element is returned | |
142 first. There is no notion of *creation* of *modification* in original | |
143 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an | |
144 existing id will overwrite the older one, creating a new item. With this option, we use | |
145 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and | |
146 *creation* time is the time when the first item has been published, before being | |
147 overwritten. | |
148 | |
149 In the case of ``modification``, if an item is overwritten, it reappears on top, this is | |
150 the default pubsub sorting order. | |
151 | |
152 progress | |
153 ======== | |
154 | |
155 This single option may be used when a long operation is happening, like a file transfer. | |
156 | |
157 ``-P, --progress`` | |
158 Show progress bar. | |
159 | |
160 verbose | |
161 ======= | |
162 | |
163 ``--verbose, -v`` | |
164 Add a verbosity level (can be used multiple times). Use to have more concise output by | |
165 default when it makes sense. | |
166 | |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
167 .. _draft_common: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
168 |
2946 | 169 draft |
170 ===== | |
171 | |
172 Common arguments used when an edition is potentially long to do, and a file may be kept | |
173 until publication. | |
174 | |
175 | |
176 ``-D, --current`` | |
177 Used when you have started to edit something (e.g. a blog post), which is not yet | |
178 published, and you want to continue your work. | |
179 | |
180 e.g.:: | |
181 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
182 $ li blog edit -D |
2946 | 183 |
184 ``-F DRAFT_PATH, --draft-path DRAFT_PATH`` | |
185 Used when you have started to edit something and want to continue your work from this | |
186 file. In other words, it's similar to ``-D, --current`` except that you specify the file | |
187 to use instead of using the last available draft. | |
188 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
189 .. _libervia-cli_output: |
3021
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2957
diff
changeset
|
190 |
2946 | 191 output |
192 ====== | |
193 | |
194 Output is used when you want to get the result of the command in a specific way. It may be | |
195 used, for instance, to retrieve the result formatted in JSON so the data can be easily | |
196 manipulated by a script, or if you want only a specific element of the result. | |
197 | |
198 ``-O {…}, --output {…}`` | |
3608
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
199 specify the output to use. Available options depends of the command you are using, |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
200 check ``li [your command] --help`` to know them. |
2946 | 201 |
202 e.g.:: | |
203 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
204 $ li blog get -O json |
2946 | 205 |
206 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` | |
207 depending of the output selected, you may have options to customise the output. | |
208 For instance, if you use the ``template`` output, you may use an option to display the | |
209 result in a browser. | |
210 | |
211 e.g.:: | |
212 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
213 $ li blog |
2946 | 214 |
215 Some options expect parameters, in this case they can be specified using ``=``. | |
216 | |
3608
6d03e8ebf1a6
doc (cli/common): explain the new `-C, --no-cache` option
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
217 e.g. specifying a template to use:: |
2946 | 218 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
219 $ li blog get -O template --oo browser --oo template=/tmp/my_template.html |
3609 | 220 |
3670
d0b66efc6c0e
doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents:
3609
diff
changeset
|
221 .. _time_pattern: |
d0b66efc6c0e
doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents:
3609
diff
changeset
|
222 |
3609 | 223 Time Pattern |
224 ============ | |
225 | |
226 When a command expect a date or date with time argument, you can use a "time pattern" (you | |
227 usually see the ``TIME_PATTERN`` as name of the argument in ``--help`` message when it can | |
228 be used). | |
229 | |
230 This is a flexible way to enter a date, you can enter a date in one of the following way: | |
231 | |
232 - the string ``now`` to indicate current date and time; | |
233 - an absolute date using an international format. The parser know many formats (please | |
234 check dateutil_ package documentation to have a detail of supported formats). Please | |
235 note that days are specified first and that if no time zone is specified, the local | |
236 time zone of your computer is assumed; | |
237 - a relative date (or "relative delta"), see below for details on how to construct it; | |
238 - a reference time (``now`` or absolute date as above) followed by a relative delta. If | |
239 the reference time is not specified, ``now`` is used; | |
240 | |
241 Time pattern is not case sensitive. | |
242 | |
243 .. _dateutil: https://dateutil.readthedocs.io | |
244 | |
245 Relative Delta | |
246 -------------- | |
247 | |
248 A relative delta is specified with: | |
249 | |
250 - an optional direction ``+`` for times after reference time or ``-`` for time before reference time (defaulting to ``+``); | |
251 - a number for the quantity of units | |
252 - a unit (e.g. seconds or minutes), see the bellow for details | |
253 - the word ``ago`` which is same as using ``-`` for direction (direction and ``ago`` can't | |
254 be used at the same time) | |
255 | |
256 Time Units | |
257 ---------- | |
258 | |
259 The singular or plural form of following units can be used: | |
260 | |
261 - ``s``, ``sec``, ``second`` | |
262 - ``m``, ``min``, ``minute`` | |
263 - ``h``, ``hr``, ``hour`` | |
264 - ``d``, ``day`` | |
265 - ``w``, ``week`` | |
266 - ``mo``, ``month`` | |
267 - ``y``, ``yr``, ``year`` | |
268 | |
269 examples | |
270 -------- | |
271 | |
272 - ``2022-01-01``: first of January of 2022 at midnight | |
273 - ``2017-02-10T13:05:00Z``: 10th of February 2017 at 13:05 UTC | |
274 - ``2019-07-14 12:00:00 CET``: 14th of July 2019 at 12:00 CET | |
275 - ``10 min ago``: current time minus 10 minutes | |
276 - ``now - 10 m``: same as above (current time minus 10 minutes) | |
277 - ``07/08/2021 +5 hours``: 7 August 2021 at midnight (local time of the computer) + 5 | |
278 hours, i.e. 5 in the morning at local time. | |
279 |