annotate doc/libervia-cli/common_arguments.rst @ 3922:0ff265725489

plugin XEP-0447: handle attachment and download: - plugin XEP-0447 can now be used in message attachments and to retrieve an attachment - plugin attach: `attachment` being processed is added to `extra` so the handler can inspect it - plugin attach: `size` is added to attachment - plugin download: a whole attachment dict is now used in `download` and `file_download`/`file_download_complete`. `download_uri` can be used as a shortcut when just a URI is used. In addition to URI scheme handler, whole attachment handlers can now be registered with `register_download_handler` - plugin XEP-0363: `file_http_upload` `XEP-0363_upload_size` triggers have been renamed to `XEP-0363_upload_pre_slot` and is now using a dict with arguments, allowing for the size but also the filename to be modified, which is necessary for encryption (filename may be hidden from URL this way). - plugin XEP-0446: fix wrong element name - plugin XEP-0447: source handler can now be registered (`url-data` is registered by default) - plugin XEP-0447: source parsing has been put in a separated `parse_sources_elt` method, as it may be useful to do it independently (notably with XEP-0448) - plugin XEP-0447: parse received message and complete attachments when suitable - plugin XEP-0447: can now be used with message attachments - plugin XEP-0447: can now be used with attachments download - renamed `options` arguments to `extra` for consistency - some style change (progressive move from legacy camelCase to PEP8 snake_case) - some typing rel 379
author Goffi <goffi@goffi.org>
date Thu, 06 Oct 2022 16:02:05 +0200
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