annotate doc/libervia-cli/common_arguments.rst @ 4180:b86912d3fd33

plugin IP: fix use of legacy URL + coroutine use: An https:/salut-a-toi.org URL was used to retrieve external IP, but it's not valid anymore, resulting in an exception. This feature is currently disabled. Also moved several methods from legacy inline callbacks to coroutines.
author Goffi <goffi@goffi.org>
date Sat, 09 Dec 2023 14:30:54 +0100
parents d0b66efc6c0e
children
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 ================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
2 common arguments
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 Some arguments are used in many commands. This page describe them.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
9 profile
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 =======
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 profile arguments are really common, they allow you to select your profile.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 If you don't select any, the default profile is used, which is the first
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 The common arguments for profile are:
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 ``-p PROFILE, --profile PROFILE``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
20 to select the name of your profile. It can be a profile key like ``@DEFAULT@``
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 ``-c, --connect``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
23 connect the profile to the XMPP server before doing anything else. If your
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 profile is already connected, nothing happen. This is specially useful in scripts.
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 ``--start-session``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
27 starts a session without connecting, this can be needed if you can't connect but
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 you need to access your session e.g. to change parameters.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 This is advanced used and is not need in most common cases.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
30
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 ``--pwd PASSWORD``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 the password of your profile, needed if the session is not started yet.
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 .. note::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 .. _pubsub_common:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
45
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
46 pubsub
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 ======
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
48
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 pubsub arguments are used in many commands, they allow you to select a service, node and
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 items. Depending on the command, you may only not be able to select an item, or you may
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
51 select one or multiple items.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
52
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 The common arguments for pubsub are:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
54
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
55 ``-u PUBSUB_URL, --pubsub-url PUBSUB_URL``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
57 ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 retrieve the location of the XMPP node/item, if available.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
59 Note that you can override parts of the location in the URL if you specify service, node
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 or item.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
61
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
62 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
65
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 ``-s SERVICE, --service``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
67 used to specifiy the JID of the pubsub service
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
68
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
69 ``-n NODE, --node NODE``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
70 used to specifiy the pubsub node
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
71
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 ``-i ITEM, --item ITEM``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
73 for commands where an item can be specified, you do it with this option. In some
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 commands, multiple items can be specified, in this case just use this arguments several
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
75 times.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
76
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 ``-L, --last-item``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
78 when an item id is needed, you can use this option to retrieve the last published item.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
80
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
81 $ li blog edit --last-item
2946
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 ``-M, --max-items``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 use to specify a maxium number of items to retrieve, when it makes sense.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
85 Note that this is using the pubsub max (i.e. defined in
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
87 implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 this case the ``-m, --max`` argument should be prefered. See below for RSM common
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
89 arguments.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
96 result set management
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 =====================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
99 Result Set Management (RSM) common arguments are used to navigate into pages of results
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 when lot of elements may be expected. Given a result with a large number of arguments, a
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 *page* is set of elements which correspond to an *index* (a page number). For instance if
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
103 20 included.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
104
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
105
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
106 ``-a ITEM_ID, --after ITEM_ID``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 find page after this item. You usually use the last item id of the latest page you got.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
108
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 ``-b ITEM_ID, --before ITEM_ID``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 find page before this item. This this usually used when you check items backwards
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 ``--index RSM_INDEX``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
113 index of the page to retrieve. Note that first page has index **0**.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
114
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 ``-m RSM_MAX, --max RSM_MAX``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
116 used to specify a maxium number of items to retrieve per page. Note that the actual
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
117 maximum number of items per page used may be lower if the service used consider that
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
118 your request is too big.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
119
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 message archive management
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 ==========================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 Message Archive Management (MAM) argument is used by some commands (related to instant message or
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 pubsub) to filter results.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
125
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
126 There is currently only one argument in this group:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
127
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
128 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 specify a MAM filter to use. Depending on the service supporting MAM, some filters can
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 be used to do things like full text search. The available filters depend on the service
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
131 you use, please check documentation of your service.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
132
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 order-by
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
134 ========
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
135
2957
8fd8c9f548cd doc (jp/common_arguments): typo
Goffi <goffi@goffi.org>
parents: 2946
diff changeset
136 Order-By argument specify how the returned elements are sorted.
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 There is currently only one argument in this group:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
139
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 ``-o {creation,modification}, --order-by {creation,modification}``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
141 specify how result is sorted. with ``creation``, first created element is returned
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
142 first. There is no notion of *creation* of *modification* in original
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
144 existing id will overwrite the older one, creating a new item. With this option, we use
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
145 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
146 *creation* time is the time when the first item has been published, before being
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 overwritten.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
148
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
149 In the case of ``modification``, if an item is overwritten, it reappears on top, this is
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 the default pubsub sorting order.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
151
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
152 progress
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 ========
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
154
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
155 This single option may be used when a long operation is happening, like a file transfer.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
156
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
157 ``-P, --progress``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
158 Show progress bar.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
159
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
160 verbose
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
161 =======
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
162
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
163 ``--verbose, -v``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
164 Add a verbosity level (can be used multiple times). Use to have more concise output by
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
165 default when it makes sense.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
169 draft
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
170 =====
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
171
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
172 Common arguments used when an edition is potentially long to do, and a file may be kept
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
173 until publication.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
174
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
175
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
176 ``-D, --current``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
177 Used when you have started to edit something (e.g. a blog post), which is not yet
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
178 published, and you want to continue your work.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
179
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
180 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
181
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
182 $ li blog edit -D
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
183
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
184 ``-F DRAFT_PATH, --draft-path DRAFT_PATH``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
185 Used when you have started to edit something and want to continue your work from this
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
186 file. In other words, it's similar to ``-D, --current`` except that you specify the file
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
187 to use instead of using the last available draft.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
191 output
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
192 ======
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
193
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
194 Output is used when you want to get the result of the command in a specific way. It may be
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
195 used, for instance, to retrieve the result formatted in JSON so the data can be easily
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
196 manipulated by a script, or if you want only a specific element of the result.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
197
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
201
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
202 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
203
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
204 $ li blog get -O json
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
205
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
206 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
207 depending of the output selected, you may have options to customise the output.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
208 For instance, if you use the ``template`` output, you may use an option to display the
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
209 result in a browser.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
210
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
211 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
212
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
213 $ li blog
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
214
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
215 Some options expect parameters, in this case they can be specified using ``=``.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
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
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
223 Time Pattern
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
224 ============
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
225
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
226 When a command expect a date or date with time argument, you can use a "time pattern" (you
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
227 usually see the ``TIME_PATTERN`` as name of the argument in ``--help`` message when it can
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
228 be used).
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
229
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
230 This is a flexible way to enter a date, you can enter a date in one of the following way:
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
231
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
232 - the string ``now`` to indicate current date and time;
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
233 - an absolute date using an international format. The parser know many formats (please
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
234 check dateutil_ package documentation to have a detail of supported formats). Please
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
235 note that days are specified first and that if no time zone is specified, the local
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
236 time zone of your computer is assumed;
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
237 - a relative date (or "relative delta"), see below for details on how to construct it;
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
238 - a reference time (``now`` or absolute date as above) followed by a relative delta. If
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
239 the reference time is not specified, ``now`` is used;
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
240
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
241 Time pattern is not case sensitive.
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
242
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
243 .. _dateutil: https://dateutil.readthedocs.io
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
244
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
245 Relative Delta
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
246 --------------
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
247
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
248 A relative delta is specified with:
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
249
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
250 - an optional direction ``+`` for times after reference time or ``-`` for time before reference time (defaulting to ``+``);
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
251 - a number for the quantity of units
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
252 - a unit (e.g. seconds or minutes), see the bellow for details
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
253 - the word ``ago`` which is same as using ``-`` for direction (direction and ``ago`` can't
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
254 be used at the same time)
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
255
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
256 Time Units
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
257 ----------
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
258
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
259 The singular or plural form of following units can be used:
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
260
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
261 - ``s``, ``sec``, ``second``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
262 - ``m``, ``min``, ``minute``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
263 - ``h``, ``hr``, ``hour``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
264 - ``d``, ``day``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
265 - ``w``, ``week``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
266 - ``mo``, ``month``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
267 - ``y``, ``yr``, ``year``
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
268
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
269 examples
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
270 --------
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
271
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
272 - ``2022-01-01``: first of January of 2022 at midnight
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
273 - ``2017-02-10T13:05:00Z``: 10th of February 2017 at 13:05 UTC
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
274 - ``2019-07-14 12:00:00 CET``: 14th of July 2019 at 12:00 CET
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
275 - ``10 min ago``: current time minus 10 minutes
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
276 - ``now - 10 m``: same as above (current time minus 10 minutes)
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
277 - ``07/08/2021 +5 hours``: 7 August 2021 at midnight (local time of the computer) + 5
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
278 hours, i.e. 5 in the morning at local time.
256faf6e951f doc (cli/common): time pattern
Goffi <goffi@goffi.org>
parents: 3608
diff changeset
279