|
2946
|
1 ================ |
|
|
2 common arguments |
|
|
3 ================ |
|
|
4 |
|
|
5 Some arguments are used in many commands. This page describe them. |
|
|
6 |
|
|
7 profile |
|
|
8 ======= |
|
|
9 |
|
|
10 profile arguments are really common, they allow you to select your profile. |
|
|
11 If you don't select any, the default profile is used, which is the first |
|
|
12 profile created or the one you have explicitly set. You can check which profile |
|
|
13 is used by default with ``jp profile default``. |
|
|
14 |
|
|
15 The common arguments for profile are: |
|
|
16 |
|
|
17 ``-p PROFILE, --profile PROFILE`` |
|
|
18 to select the name of your profile. It can be a profile key like ``@DEFAULT@`` |
|
|
19 |
|
|
20 ``-c, --connect`` |
|
|
21 connect the profile to the XMPP server before doing anything else. If your |
|
|
22 profile is already connected, nothing happen. This is specially useful in scripts. |
|
|
23 |
|
|
24 ``--start-session`` |
|
|
25 starts a session without connecting, this can be needed if you can't connect but |
|
|
26 you need to access your session e.g. to change parameters. |
|
|
27 This is advanced used and is not need in most common cases. |
|
|
28 |
|
|
29 ``--pwd PASSWORD`` |
|
|
30 the password of your profile, needed if the session is not started yet. |
|
|
31 |
|
|
32 .. note:: |
|
|
33 |
|
|
34 jp does not yet prompt for password when needed, this mean that using the ``--pwd`` |
|
|
35 option is not secure if you are not the only user of your machine: the password will |
|
|
36 appear **IN CLEAR** in the list of launched process, or in the history of your shell. |
|
|
37 If you are on a shared machine or if anybody can access your shell history at some |
|
|
38 point, you should connect first your profile with an other frontend (Primitivus for |
|
|
39 instance). This will be fixed in a future version of jp. |
|
|
40 |
|
|
41 .. _pubsub_common: |
|
|
42 |
|
|
43 pubsub |
|
|
44 ====== |
|
|
45 |
|
|
46 pubsub arguments are used in many commands, they allow you to select a service, node and |
|
|
47 items. Depending on the command, you may only not be able to select an item, or you may |
|
|
48 select one or multiple items. |
|
|
49 |
|
|
50 The common arguments for pubsub are: |
|
|
51 |
|
|
52 ``-u PUBSUB_URL, --pubsub-url PUBSUB_URL`` |
|
|
53 retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an |
|
|
54 ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to |
|
|
55 retrieve the location of the XMPP node/item, if available. |
|
|
56 Note that you can override parts of the location in the URL if you specify service, node |
|
|
57 or item. |
|
|
58 |
|
|
59 e.g.:: |
|
|
60 |
|
|
61 $ jp blog get -u https://www.goffi.org |
|
|
62 |
|
|
63 ``-s SERVICE, --service`` |
|
|
64 used to specifiy the JID of the pubsub service |
|
|
65 |
|
|
66 ``-n NODE, --node NODE`` |
|
|
67 used to specifiy the pubsub node |
|
|
68 |
|
|
69 ``-i ITEM, --item ITEM`` |
|
|
70 for commands where an item can be specified, you do it with this option. In some |
|
|
71 commands, multiple items can be specified, in this case just use this arguments several |
|
|
72 times. |
|
|
73 |
|
|
74 ``-L, --last-item`` |
|
|
75 when an item id is needed, you can use this option to retrieve the last published item. |
|
|
76 e.g.:: |
|
|
77 |
|
|
78 $ jp blog edit --last-item |
|
|
79 |
|
|
80 ``-M, --max-items`` |
|
|
81 use to specify a maxium number of items to retrieve, when it makes sense. |
|
|
82 Note that this is using the pubsub max (i.e. defined in |
|
|
83 `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should |
|
|
84 implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in |
|
|
85 this case the ``-m, --max`` argument should be prefered. See below for RSM common |
|
|
86 arguments. |
|
|
87 |
|
|
88 result set management |
|
|
89 ===================== |
|
|
90 |
|
|
91 Result Set Management (RSM) common arguments are used to navigate into pages of results |
|
|
92 when lot of elements may be expected. Given a result with a large number of arguments, a |
|
|
93 *page* is set of elements which correspond to an *index* (a page number). For instance if |
|
|
94 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to |
|
|
95 20 included. |
|
|
96 |
|
|
97 |
|
|
98 ``-a ITEM_ID, --after ITEM_ID`` |
|
|
99 find page after this item. You usually use the last item id of the latest page you got. |
|
|
100 |
|
|
101 ``-b ITEM_ID, --before ITEM_ID`` |
|
|
102 find page before this item. This this usually used when you check items backwards |
|
|
103 |
|
|
104 ``--index RSM_INDEX`` |
|
|
105 index of the page to retrieve. Note that first page has index **0**. |
|
|
106 |
|
|
107 ``-m RSM_MAX, --max RSM_MAX`` |
|
|
108 used to specify a maxium number of items to retrieve per page. Note that the actual |
|
|
109 maximum number of items per page used may be lower if the service used consider that |
|
|
110 your request is too big. |
|
|
111 |
|
|
112 message archive management |
|
|
113 ========================== |
|
|
114 |
|
|
115 Message Archive Management (MAM) argument is used by some commands (related to instant message or |
|
|
116 pubsub) to filter results. |
|
|
117 |
|
|
118 There is currently only one argument in this group: |
|
|
119 |
|
|
120 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` |
|
|
121 specify a MAM filter to use. Depending on the service supporting MAM, some filters can |
|
|
122 be used to do things like full text search. The available filters depend on the service |
|
|
123 you use, please check documentation of your service. |
|
|
124 |
|
|
125 order-by |
|
|
126 ======== |
|
|
127 |
|
2957
|
128 Order-By argument specify how the returned elements are sorted. |
|
2946
|
129 |
|
|
130 There is currently only one argument in this group: |
|
|
131 |
|
|
132 ``-o {creation,modification}, --order-by {creation,modification}`` |
|
|
133 specify how result is sorted. with ``creation``, first created element is returned |
|
|
134 first. There is no notion of *creation* of *modification* in original |
|
|
135 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an |
|
|
136 existing id will overwrite the older one, creating a new item. With this option, we use |
|
|
137 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and |
|
|
138 *creation* time is the time when the first item has been published, before being |
|
|
139 overwritten. |
|
|
140 |
|
|
141 In the case of ``modification``, if an item is overwritten, it reappears on top, this is |
|
|
142 the default pubsub sorting order. |
|
|
143 |
|
|
144 progress |
|
|
145 ======== |
|
|
146 |
|
|
147 This single option may be used when a long operation is happening, like a file transfer. |
|
|
148 |
|
|
149 ``-P, --progress`` |
|
|
150 Show progress bar. |
|
|
151 |
|
|
152 verbose |
|
|
153 ======= |
|
|
154 |
|
|
155 ``--verbose, -v`` |
|
|
156 Add a verbosity level (can be used multiple times). Use to have more concise output by |
|
|
157 default when it makes sense. |
|
|
158 |
|
|
159 draft |
|
|
160 ===== |
|
|
161 |
|
|
162 Common arguments used when an edition is potentially long to do, and a file may be kept |
|
|
163 until publication. |
|
|
164 |
|
|
165 |
|
|
166 ``-D, --current`` |
|
|
167 Used when you have started to edit something (e.g. a blog post), which is not yet |
|
|
168 published, and you want to continue your work. |
|
|
169 |
|
|
170 e.g.:: |
|
|
171 |
|
|
172 $ jp blog edit -D |
|
|
173 |
|
|
174 ``-F DRAFT_PATH, --draft-path DRAFT_PATH`` |
|
|
175 Used when you have started to edit something and want to continue your work from this |
|
|
176 file. In other words, it's similar to ``-D, --current`` except that you specify the file |
|
|
177 to use instead of using the last available draft. |
|
|
178 |
|
|
179 output |
|
|
180 ====== |
|
|
181 |
|
|
182 Output is used when you want to get the result of the command in a specific way. It may be |
|
|
183 used, for instance, to retrieve the result formatted in JSON so the data can be easily |
|
|
184 manipulated by a script, or if you want only a specific element of the result. |
|
|
185 |
|
|
186 ``-O {…}, --output {…}`` |
|
|
187 specifiy the output to use. Available options depends of the command you are using, |
|
|
188 check ``jp [your command] --help`` to know them. |
|
|
189 |
|
|
190 e.g.:: |
|
|
191 |
|
|
192 $ jp blog get -O json |
|
|
193 |
|
|
194 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` |
|
|
195 depending of the output selected, you may have options to customise the output. |
|
|
196 For instance, if you use the ``template`` output, you may use an option to display the |
|
|
197 result in a browser. |
|
|
198 |
|
|
199 e.g.:: |
|
|
200 |
|
|
201 $ jp blog |
|
|
202 |
|
|
203 Some options expect parameters, in this case they can be specified using ``=``. |
|
|
204 |
|
|
205 e.g. specifiying a template to use:: |
|
|
206 |
|
|
207 $ jp blog get -O template --oo browser --oo template=/tmp/my_template.html |
