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
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 result set management
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 =====================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 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
95 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
96 *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
97 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
98 20 included.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
99
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
100
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 ``-a ITEM_ID, --after ITEM_ID``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 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
103
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 ``-b ITEM_ID, --before ITEM_ID``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 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
106
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 ``--index RSM_INDEX``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
108 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
109
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 ``-m RSM_MAX, --max RSM_MAX``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
111 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
112 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
113 your request is too big.
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 message archive management
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
116 ==========================
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
117
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
118 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
119 pubsub) to filter results.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
120
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 There is currently only one argument in this group:
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 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 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
125 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
126 you use, please check documentation of your service.
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 order-by
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 ========
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
130
2957
8fd8c9f548cd doc (jp/common_arguments): typo
Goffi <goffi@goffi.org>
parents: 2946
diff changeset
131 Order-By argument specify how the returned elements are sorted.
2946
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 There is currently only one argument in this group:
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 ``-o {creation,modification}, --order-by {creation,modification}``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 specify how result is sorted. with ``creation``, first created element is returned
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
137 first. There is no notion of *creation* of *modification* in original
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 `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
139 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
140 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
141 *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
142 overwritten.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
143
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
144 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
145 the default pubsub sorting order.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
146
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 progress
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 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
151
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
152 ``-P, --progress``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 Show progress bar.
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 verbose
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
158 ``--verbose, -v``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
159 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
160 default when it makes sense.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
164 draft
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
165 =====
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
166
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
167 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
168 until publication.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
169
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 ``-D, --current``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
172 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
173 published, and you want to continue your work.
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 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
176
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
177 $ li blog edit -D
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
178
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
179 ``-F DRAFT_PATH, --draft-path DRAFT_PATH``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
180 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
181 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
182 to use instead of using the last available draft.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
186 output
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
187 ======
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
188
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
189 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
190 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
191 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
192
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
193 ``-O {…}, --output {…}``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
196
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
197 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
198
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
199 $ li blog get -O json
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
200
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
201 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS``
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
202 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
203 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
204 result in a browser.
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 e.g.::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
207
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3050
diff changeset
208 $ li blog
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
209
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
210 Some options expect parameters, in this case they can be specified using ``=``.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
211
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
212 e.g. specifiying a template to use::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
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