doc/sdk/cli/subcommands.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Command line tools (CLI SDK)
   5 title: "arv subcommands"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 _In order to use the @arv@ command, make sure that you have a "working environment.":{{site.baseurl}}/user/getting_started/check-environment.html_
  15
  16 h3(#arv-create). arv create
  17
  18 @arv create@ can be used to create Arvados objects from the command line. Arv create opens up the editor of your choice (set the EDITOR environment variable) and allows you to type or paste a json or yaml description. When saved the object will be created on the API server, if it passes validation.
  19
  20 <notextile>
  21 <pre>
  22 $ <code class="userinput">arv create --help</code>
  23 Options:
  24   --project-uuid, -p &lt;s&gt;:   Project uuid in which to create the object
  25               --help, -h:   Show this message
  26 </pre>
  27 </notextile>
  28
  29 h3(#arv-get). arv get
  30
  31 @arv get@ can be used to get a textual representation of Arvados objects from the command line. The output can be limited to a subset of the object's fields. This command can be used with only the knowledge of an object's UUID.
  32
  33 <notextile>
  34 <pre>
  35 $ <code class="userinput">arv get --help</code>
  36 Usage: arv [--format json|yaml] get [uuid] [fields...]
  37
  38 Fetch the specified Arvados object, select the specified fields,
  39 and print a text representation.
  40 </pre>
  41 </notextile>
  42
  43 h3(#arv-edit). arv edit
  44
  45 @arv edit@ can be used to edit Arvados objects from the command line. Arv edit opens up the editor of your choice (set the EDITOR environment variable) with the json or yaml description of the object. Saving the file will update the Arvados object on the API server, if it passes validation.
  46
  47 <notextile>
  48 <pre>
  49 $ <code class="userinput">arv edit --help</code>
  50 Arvados command line client
  51 Usage: arv edit [uuid] [fields...]
  52
  53 Fetch the specified Arvados object, select the specified fields,
  54 open an interactive text editor on a text representation (json or
  55 yaml, use --format) and then update the object.  Will use 'nano'
  56 by default, customize with the EDITOR or VISUAL environment variable.
  57 </pre>
  58 </notextile>
  59
  60 h3(#arv-copy). arv copy
  61
  62 @arv copy@ can be used to copy a pipeline instance, template or collection from one Arvados instance to another. It takes care of copying the object and all its dependencies.
  63
  64 <notextile>
  65 <pre>
  66 $ <code class="userinput">arv copy --help</code>
  67 usage: arv-copy [-h] [--version] [-v] [--progress] [--no-progress] [-f]
  68                 [--src SOURCE_ARVADOS] [--dst DESTINATION_ARVADOS]
  69                 [--recursive] [--no-recursive] [--project-uuid PROJECT_UUID]
  70                 [--storage-classes STORAGE_CLASSES]
  71                 [--varying-url-params VARYING_URL_PARAMS]
  72                 [--prefer-cached-downloads] [--retries RETRIES]
  73                 object_uuid
  74
  75 Copy a workflow, collection or project from one Arvados instance to another.
  76 On success, the uuid of the copied object is printed to stdout.
  77
  78 positional arguments:
  79   object_uuid           The UUID of the object to be copied.
  80
  81 optional arguments:
  82   -h, --help            show this help message and exit
  83   --version             Print version and exit.
  84   -v, --verbose         Verbose output.
  85   --progress            Report progress on copying collections. (default)
  86   --no-progress         Do not report progress on copying collections.
  87   -f, --force           Perform copy even if the object appears to exist at
  88                         the remote destination.
  89   --src SOURCE_ARVADOS  Client configuration location for the source Arvados
  90                         cluster. May be either a configuration file path, or a
  91                         plain identifier like `foo` to search for a
  92                         configuration file `foo.conf` under a systemd or XDG
  93                         configuration directory. If not provided, will search
  94                         for a configuration file named after the cluster ID of
  95                         the source object UUID.
  96   --dst DESTINATION_ARVADOS
  97                         Client configuration location for the destination
  98                         Arvados cluster. May be either a configuration file
  99                         path, or a plain identifier like `foo` to search for a
 100                         configuration file `foo.conf` under a systemd or XDG
 101                         configuration directory. If not provided, will use the
 102                         default client configuration from the environment or
 103                         `settings.conf`.
 104   --recursive           Recursively copy any dependencies for this object, and
 105                         subprojects. (default)
 106   --no-recursive        Do not copy any dependencies or subprojects.
 107   --project-uuid PROJECT_UUID
 108                         The UUID of the project at the destination to which
 109                         the collection or workflow should be copied.
 110   --storage-classes STORAGE_CLASSES
 111                         Comma separated list of storage classes to be used
 112                         when saving data to the destinaton Arvados instance.
 113   --varying-url-params VARYING_URL_PARAMS
 114                         A comma separated list of URL query parameters that
 115                         should be ignored when storing HTTP URLs in Keep.
 116   --prefer-cached-downloads
 117                         If a HTTP URL is found in Keep, skip upstream URL
 118                         freshness check (will not notice if the upstream has
 119                         changed, but also not error if upstream is
 120                         unavailable).
 121   --retries RETRIES     Maximum number of times to retry server requests that
 122                         encounter temporary failures (e.g., server down).
 123                         Default 10.
 124 </pre>
 125 </notextile>
 126
 127 h3(#arv-tag). arv tag
 128
 129 @arv tag@ is used to tag Arvados objects.
 130
 131 <notextile>
 132 <pre>
 133 $ <code class="userinput">arv tag --help</code>
 134
 135 Usage:
 136 arv tag add tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 137 arv tag remove tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 138 arv tag remove --all
 139
 140   --dry-run, -n:   Don't actually do anything
 141   --verbose, -v:   Print some things on stderr
 142      --uuid, -u:   Return the UUIDs of the objects in the response, one per
 143                    line (default)
 144      --json, -j:   Return the entire response received from the API server, as
 145                    a JSON object
 146     --human, -h:   Return the response received from the API server, as a JSON
 147                    object with whitespace added for human consumption
 148    --pretty, -p:   Synonym of --human
 149      --yaml, -y:   Return the response received from the API server, in YAML
 150                    format
 151      --help, -e:   Show this message
 152 </pre>
 153 </notextile>
 154
 155
 156 h3(#arv-ws). arv ws
 157
 158 This is a frontend to @arv-ws@.
 159
 160 @arv ws@ provides access to the websockets event stream.
 161
 162 <notextile>
 163 <pre>
 164 $ <code class="userinput">arv ws --help</code>
 165 usage: arv-ws [-h] [-u UUID] [-f FILTERS]
 166               [--poll-interval POLL_INTERVAL | --no-poll]
 167               [-p PIPELINE | -j JOB]
 168
 169 optional arguments:
 170   -h, --help            show this help message and exit
 171   -u UUID, --uuid UUID  Filter events on object_uuid
 172   -f FILTERS, --filters FILTERS
 173                         Arvados query filter to apply to log events (JSON
 174                         encoded)
 175   --poll-interval POLL_INTERVAL
 176                         If websockets is not available, specify the polling
 177                         interval, default is every 15 seconds
 178   --no-poll             Do not poll if websockets are not available, just fail
 179   -p PIPELINE, --pipeline PIPELINE
 180                         Supply pipeline uuid, print log output from pipeline
 181                         and its jobs
 182   -j JOB, --job JOB     Supply job uuid, print log output from jobs
 183 </pre>
 184 </notextile>
 185
 186 h3(#arv-keep). arv keep
 187
 188 @arv keep@ commands for accessing the Keep storage service.
 189
 190 <notextile>
 191 <pre>
 192 $ <code class="userinput">arv keep --help</code>
 193 Usage: arv keep [method] [--parameters]
 194 Use 'arv keep [method] --help' to get more information about specific methods.
 195
 196 Available methods: ls, get, put, docker
 197 </pre>
 198 </notextile>
 199
 200 h3(#arv-keep-ls). arv keep ls
 201
 202 This is a frontend to @arv-ls@.
 203
 204 <notextile>
 205 <pre>
 206 $ <code class="userinput">arv keep ls --help</code>
 207 usage: arv-ls [-h] [--retries RETRIES] [-s] locator
 208
 209 List contents of a manifest
 210
 211 positional arguments:
 212   locator            Collection UUID or locator
 213
 214 optional arguments:
 215   -h, --help         show this help message and exit
 216   --retries RETRIES  Maximum number of times to retry server requests that
 217                      encounter temporary failures (e.g., server down). Default
 218                      3.
 219   -s                 List file sizes, in KiB.
 220 </pre>
 221 </notextile>
 222
 223 h3(#arv-keep-get). arv keep get
 224
 225 This is a frontend to @arv-get@.
 226
 227 <notextile>
 228 <pre>
 229 $ <code class="userinput">arv keep get --help</code>
 230 usage: arv-get [-h] [--retries RETRIES] [--version]
 231                [--progress | --no-progress | --batch-progress]
 232                [--hash HASH | --md5sum] [-n] [-r]
 233                [-f | -v | --skip-existing | --strip-manifest] [--threads N]
 234                locator [destination]
 235
 236 Copy data from Keep to a local file or pipe.
 237
 238 positional arguments:
 239   locator            Collection locator, optionally with a file path or
 240                      prefix.
 241   destination        Local file or directory where the data is to be written.
 242                      Default: stdout.
 243
 244 optional arguments:
 245   -h, --help         show this help message and exit
 246   --retries RETRIES  Maximum number of times to retry server requests that
 247                      encounter temporary failures (e.g., server down).
 248                      Default 3.
 249   --version          Print version and exit.
 250   --progress         Display human-readable progress on stderr (bytes and, if
 251                      possible, percentage of total data size). This is the
 252                      default behavior when it is not expected to interfere
 253                      with the output: specifically, stderr is a tty _and_
 254                      either stdout is not a tty, or output is being written
 255                      to named files rather than stdout.
 256   --no-progress      Do not display human-readable progress on stderr.
 257   --batch-progress   Display machine-readable progress on stderr (bytes and,
 258                      if known, total data size).
 259   --hash HASH        Display the hash of each file as it is read from Keep,
 260                      using the given hash algorithm. Supported algorithms
 261                      include md5, sha1, sha224, sha256, sha384, and sha512.
 262   --md5sum           Display the MD5 hash of each file as it is read from
 263                      Keep.
 264   -n                 Do not write any data -- just read from Keep, and report
 265                      md5sums if requested.
 266   -r                 Retrieve all files in the specified collection/prefix.
 267                      This is the default behavior if the "locator" argument
 268                      ends with a forward slash.
 269   -f                 Overwrite existing files while writing. The default
 270                      behavior is to refuse to write *anything* if any of the
 271                      output files already exist. As a special case, -f is not
 272                      needed to write to stdout.
 273   -v                 Once for verbose mode, twice for debug mode.
 274   --skip-existing    Skip files that already exist. The default behavior is
 275                      to refuse to write *anything* if any files exist that
 276                      would have to be overwritten. This option causes even
 277                      devices, sockets, and fifos to be skipped.
 278   --strip-manifest   When getting a collection manifest, strip its access
 279                      tokens before writing it.
 280   --threads N        Set the number of download threads to be used. Take into
 281                      account that using lots of threads will increase the RAM
 282                      requirements. Default is to use 4 threads. On high
 283                      latency installations, using a greater number will
 284                      improve overall throughput.
 285 </pre>
 286 </notextile>
 287
 288 h3(#arv-keep-put). arv keep put
 289
 290 This is a frontend to @arv-put@.
 291
 292 <notextile>
 293 <pre>
 294 $ <code class="userinput">arv keep put --help</code>
 295 usage: arv-put [-h] [--max-manifest-depth N | --normalize]
 296                [--as-stream | --stream | --as-manifest | --in-manifest | --manifest | --as-raw | --raw]
 297                [--use-filename FILENAME] [--filename FILENAME]
 298                [--portable-data-hash] [--replication N]
 299                [--project-uuid UUID] [--name NAME]
 300                [--progress | --no-progress | --batch-progress]
 301                [--resume | --no-resume] [--retries RETRIES]
 302                [path [path ...]]
 303
 304 Copy data from the local filesystem to Keep.
 305
 306 positional arguments:
 307   path                  Local file or directory. Default: read from standard
 308                         input.
 309
 310 optional arguments:
 311   -h, --help            show this help message and exit
 312   --max-manifest-depth N
 313                         Maximum depth of directory tree to represent in the
 314                         manifest structure. A directory structure deeper than
 315                         this will be represented as a single stream in the
 316                         manifest. If N=0, the manifest will contain a single
 317                         stream. Default: -1 (unlimited), i.e., exactly one
 318                         manifest stream per filesystem directory that contains
 319                         files.
 320   --normalize           Normalize the manifest by re-ordering files and
 321                         streams after writing data.
 322   --as-stream           Synonym for --stream.
 323   --stream              Store the file content and display the resulting
 324                         manifest on stdout. Do not write the manifest to Keep
 325                         or save a Collection object in Arvados.
 326   --as-manifest         Synonym for --manifest.
 327   --in-manifest         Synonym for --manifest.
 328   --manifest            Store the file data and resulting manifest in Keep,
 329                         save a Collection object in Arvados, and display the
 330                         manifest locator (Collection uuid) on stdout. This is
 331                         the default behavior.
 332   --as-raw              Synonym for --raw.
 333   --raw                 Store the file content and display the data block
 334                         locators on stdout, separated by commas, with a
 335                         trailing newline. Do not store a manifest.
 336   --use-filename FILENAME
 337                         Synonym for --filename.
 338   --filename FILENAME   Use the given filename in the manifest, instead of the
 339                         name of the local file. This is useful when "-" or
 340                         "/dev/stdin" is given as an input file. It can be used
 341                         only if there is exactly one path given and it is not
 342                         a directory. Implies --manifest.
 343   --portable-data-hash  Print the portable data hash instead of the Arvados
 344                         UUID for the collection created by the upload.
 345   --replication N       Set the replication level for the new collection: how
 346                         many different physical storage devices (e.g., disks)
 347                         should have a copy of each data block. Default is to
 348                         use the server-provided default (if any) or 2.
 349   --project-uuid UUID   Store the collection in the specified project, instead
 350                         of your Home project.
 351   --name NAME           Save the collection with the specified name.
 352   --progress            Display human-readable progress on stderr (bytes and,
 353                         if possible, percentage of total data size). This is
 354                         the default behavior when stderr is a tty.
 355   --no-progress         Do not display human-readable progress on stderr, even
 356                         if stderr is a tty.
 357   --batch-progress      Display machine-readable progress on stderr (bytes
 358                         and, if known, total data size).
 359   --resume              Continue interrupted uploads from cached state
 360                         (default).
 361   --no-resume           Do not continue interrupted uploads from cached state.
 362   --retries RETRIES     Maximum number of times to retry server requests that
 363                         encounter temporary failures (e.g., server down).
 364                         Default 3.
 365 </pre>
 366 </notextile>