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
