Mercurial > libervia-backend
annotate doc/libervia-cli/common_arguments.rst @ 3652:6e34307319c0
plugin XEP-0353: fix jingle initiation on disco "Service Unavailable" error:
When requesting disco info on a bare jid which is not in our roster, server may return
"Service Unavailable" (to avoid leaking valid JIDs). In this case, the initiation was
failing, this is now fixed by using empty categories in this case.
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 08 Sep 2021 11:16:52 +0200 |
| parents | c80a0f864b5d |
| children | 6d03e8ebf1a6 |
| 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 | |
| 91 result set management | |
| 92 ===================== | |
| 93 | |
| 94 Result Set Management (RSM) common arguments are used to navigate into pages of results | |
| 95 when lot of elements may be expected. Given a result with a large number of arguments, a | |
| 96 *page* is set of elements which correspond to an *index* (a page number). For instance if | |
| 97 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to | |
| 98 20 included. | |
| 99 | |
| 100 | |
| 101 ``-a ITEM_ID, --after ITEM_ID`` | |
| 102 find page after this item. You usually use the last item id of the latest page you got. | |
| 103 | |
| 104 ``-b ITEM_ID, --before ITEM_ID`` | |
| 105 find page before this item. This this usually used when you check items backwards | |
| 106 | |
| 107 ``--index RSM_INDEX`` | |
| 108 index of the page to retrieve. Note that first page has index **0**. | |
| 109 | |
| 110 ``-m RSM_MAX, --max RSM_MAX`` | |
| 111 used to specify a maxium number of items to retrieve per page. Note that the actual | |
| 112 maximum number of items per page used may be lower if the service used consider that | |
| 113 your request is too big. | |
| 114 | |
| 115 message archive management | |
| 116 ========================== | |
| 117 | |
| 118 Message Archive Management (MAM) argument is used by some commands (related to instant message or | |
| 119 pubsub) to filter results. | |
| 120 | |
| 121 There is currently only one argument in this group: | |
| 122 | |
| 123 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` | |
| 124 specify a MAM filter to use. Depending on the service supporting MAM, some filters can | |
| 125 be used to do things like full text search. The available filters depend on the service | |
| 126 you use, please check documentation of your service. | |
| 127 | |
| 128 order-by | |
| 129 ======== | |
| 130 | |
| 2957 | 131 Order-By argument specify how the returned elements are sorted. |
| 2946 | 132 |
| 133 There is currently only one argument in this group: | |
| 134 | |
| 135 ``-o {creation,modification}, --order-by {creation,modification}`` | |
| 136 specify how result is sorted. with ``creation``, first created element is returned | |
| 137 first. There is no notion of *creation* of *modification* in original | |
| 138 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an | |
| 139 existing id will overwrite the older one, creating a new item. With this option, we use | |
| 140 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and | |
| 141 *creation* time is the time when the first item has been published, before being | |
| 142 overwritten. | |
| 143 | |
| 144 In the case of ``modification``, if an item is overwritten, it reappears on top, this is | |
| 145 the default pubsub sorting order. | |
| 146 | |
| 147 progress | |
| 148 ======== | |
| 149 | |
| 150 This single option may be used when a long operation is happening, like a file transfer. | |
| 151 | |
| 152 ``-P, --progress`` | |
| 153 Show progress bar. | |
| 154 | |
| 155 verbose | |
| 156 ======= | |
| 157 | |
| 158 ``--verbose, -v`` | |
| 159 Add a verbosity level (can be used multiple times). Use to have more concise output by | |
| 160 default when it makes sense. | |
| 161 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
162 .. _draft_common: |
|
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
163 |
| 2946 | 164 draft |
| 165 ===== | |
| 166 | |
| 167 Common arguments used when an edition is potentially long to do, and a file may be kept | |
| 168 until publication. | |
| 169 | |
| 170 | |
| 171 ``-D, --current`` | |
| 172 Used when you have started to edit something (e.g. a blog post), which is not yet | |
| 173 published, and you want to continue your work. | |
| 174 | |
| 175 e.g.:: | |
| 176 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
177 $ li blog edit -D |
| 2946 | 178 |
| 179 ``-F DRAFT_PATH, --draft-path DRAFT_PATH`` | |
| 180 Used when you have started to edit something and want to continue your work from this | |
| 181 file. In other words, it's similar to ``-D, --current`` except that you specify the file | |
| 182 to use instead of using the last available draft. | |
| 183 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
184 .. _libervia-cli_output: |
|
3021
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2957
diff
changeset
|
185 |
| 2946 | 186 output |
| 187 ====== | |
| 188 | |
| 189 Output is used when you want to get the result of the command in a specific way. It may be | |
| 190 used, for instance, to retrieve the result formatted in JSON so the data can be easily | |
| 191 manipulated by a script, or if you want only a specific element of the result. | |
| 192 | |
| 193 ``-O {…}, --output {…}`` | |
| 194 specifiy the output to use. Available options depends of the command you are using, | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
195 check ``li [your command] --help`` to know them. |
| 2946 | 196 |
| 197 e.g.:: | |
| 198 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
199 $ li blog get -O json |
| 2946 | 200 |
| 201 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` | |
| 202 depending of the output selected, you may have options to customise the output. | |
| 203 For instance, if you use the ``template`` output, you may use an option to display the | |
| 204 result in a browser. | |
| 205 | |
| 206 e.g.:: | |
| 207 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
208 $ li blog |
| 2946 | 209 |
| 210 Some options expect parameters, in this case they can be specified using ``=``. | |
| 211 | |
| 212 e.g. specifiying a template to use:: | |
| 213 | |
|
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3050
diff
changeset
|
214 $ li blog get -O template --oo browser --oo template=/tmp/my_template.html |