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.py [-h] [-v] [--progress] [--no-progress] [-f] --src
  68                    SOURCE_ARVADOS --dst DESTINATION_ARVADOS [--recursive]
  69                    [--no-recursive] [--dst-git-repo DST_GIT_REPO]
  70                    [--project-uuid PROJECT_UUID] [--retries RETRIES]
  71                    object_uuid
  72
  73 Copy a pipeline instance, template or collection from one Arvados instance to
  74 another.
  75
  76 positional arguments:
  77   object_uuid           The UUID of the object to be copied.
  78
  79 optional arguments:
  80   -h, --help            show this help message and exit
  81   -v, --verbose         Verbose output.
  82   --progress            Report progress on copying collections. (default)
  83   --no-progress         Do not report progress on copying collections.
  84   -f, --force           Perform copy even if the object appears to exist at
  85                         the remote destination.
  86   --src SOURCE_ARVADOS  The name of the source Arvados instance (required) -
  87                         points at an Arvados config file. May be either a
  88                         pathname to a config file, or (for example) "foo" as
  89                         shorthand for $HOME/.config/arvados/foo.conf.
  90   --dst DESTINATION_ARVADOS
  91                         The name of the destination Arvados instance
  92                         (required) - points at an Arvados config file. May be
  93                         either a pathname to a config file, or (for example)
  94                         "foo" as shorthand for $HOME/.config/arvados/foo.conf.
  95   --recursive           Recursively copy any dependencies for this object.
  96                         (default)
  97   --no-recursive        Do not copy any dependencies. NOTE: if this option is
  98                         given, the copied object will need to be updated
  99                         manually in order to be functional.
 100   --dst-git-repo DST_GIT_REPO
 101                         The name of the destination git repository. Required
 102                         when copying a pipeline recursively.
 103   --project-uuid PROJECT_UUID
 104                         The UUID of the project at the destination to which
 105                         the pipeline should be copied.
 106   --retries RETRIES     Maximum number of times to retry server requests that
 107                         encounter temporary failures (e.g., server down).
 108                         Default 3.
 109 </pre>
 110 </notextile>
 111
 112 h3(#arv-tag). arv tag
 113
 114 @arv tag@ is used to tag Arvados objects.
 115
 116 <notextile>
 117 <pre>
 118 $ <code class="userinput">arv tag --help</code>
 119
 120 Usage:
 121 arv tag add tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 122 arv tag remove tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 123 arv tag remove --all
 124
 125   --dry-run, -n:   Don't actually do anything
 126   --verbose, -v:   Print some things on stderr
 127      --uuid, -u:   Return the UUIDs of the objects in the response, one per
 128                    line (default)
 129      --json, -j:   Return the entire response received from the API server, as
 130                    a JSON object
 131     --human, -h:   Return the response received from the API server, as a JSON
 132                    object with whitespace added for human consumption
 133    --pretty, -p:   Synonym of --human
 134      --yaml, -y:   Return the response received from the API server, in YAML
 135                    format
 136      --help, -e:   Show this message
 137 </pre>
 138 </notextile>
 139
 140
 141 h3(#arv-ws). arv ws
 142
 143 This is a frontend to @arv-ws@.
 144
 145 @arv ws@ provides access to the websockets event stream.
 146
 147 <notextile>
 148 <pre>
 149 $ <code class="userinput">arv ws --help</code>
 150 usage: arv-ws [-h] [-u UUID] [-f FILTERS]
 151               [--poll-interval POLL_INTERVAL | --no-poll]
 152               [-p PIPELINE | -j JOB]
 153
 154 optional arguments:
 155   -h, --help            show this help message and exit
 156   -u UUID, --uuid UUID  Filter events on object_uuid
 157   -f FILTERS, --filters FILTERS
 158                         Arvados query filter to apply to log events (JSON
 159                         encoded)
 160   --poll-interval POLL_INTERVAL
 161                         If websockets is not available, specify the polling
 162                         interval, default is every 15 seconds
 163   --no-poll             Do not poll if websockets are not available, just fail
 164   -p PIPELINE, --pipeline PIPELINE
 165                         Supply pipeline uuid, print log output from pipeline
 166                         and its jobs
 167   -j JOB, --job JOB     Supply job uuid, print log output from jobs
 168 </pre>
 169 </notextile>
 170
 171 h3(#arv-keep). arv keep
 172
 173 @arv keep@ commands for accessing the Keep storage service.
 174
 175 <notextile>
 176 <pre>
 177 $ <code class="userinput">arv keep --help</code>
 178 Usage: arv keep [method] [--parameters]
 179 Use 'arv keep [method] --help' to get more information about specific methods.
 180
 181 Available methods: ls, get, put, docker
 182 </pre>
 183 </notextile>
 184
 185 h3(#arv-keep-ls). arv keep ls
 186
 187 This is a frontend to @arv-ls@.
 188
 189 <notextile>
 190 <pre>
 191 $ <code class="userinput">arv keep ls --help</code>
 192 usage: arv-ls [-h] [--retries RETRIES] [-s] locator
 193
 194 List contents of a manifest
 195
 196 positional arguments:
 197   locator            Collection UUID or locator
 198
 199 optional arguments:
 200   -h, --help         show this help message and exit
 201   --retries RETRIES  Maximum number of times to retry server requests that
 202                      encounter temporary failures (e.g., server down). Default
 203                      3.
 204   -s                 List file sizes, in KiB.
 205 </pre>
 206 </notextile>
 207
 208 h3(#arv-keep-get). arv keep get
 209
 210 This is a frontend to @arv-get@.
 211
 212 <notextile>
 213 <pre>
 214 $ <code class="userinput">arv keep get --help</code>
 215 usage: arv-get [-h] [--retries RETRIES] [--version]
 216                [--progress | --no-progress | --batch-progress]
 217                [--hash HASH | --md5sum] [-n] [-r]
 218                [-f | -v | --skip-existing | --strip-manifest] [--threads N]
 219                locator [destination]
 220
 221 Copy data from Keep to a local file or pipe.
 222
 223 positional arguments:
 224   locator            Collection locator, optionally with a file path or
 225                      prefix.
 226   destination        Local file or directory where the data is to be written.
 227                      Default: stdout.
 228
 229 optional arguments:
 230   -h, --help         show this help message and exit
 231   --retries RETRIES  Maximum number of times to retry server requests that
 232                      encounter temporary failures (e.g., server down).
 233                      Default 3.
 234   --version          Print version and exit.
 235   --progress         Display human-readable progress on stderr (bytes and, if
 236                      possible, percentage of total data size). This is the
 237                      default behavior when it is not expected to interfere
 238                      with the output: specifically, stderr is a tty _and_
 239                      either stdout is not a tty, or output is being written
 240                      to named files rather than stdout.
 241   --no-progress      Do not display human-readable progress on stderr.
 242   --batch-progress   Display machine-readable progress on stderr (bytes and,
 243                      if known, total data size).
 244   --hash HASH        Display the hash of each file as it is read from Keep,
 245                      using the given hash algorithm. Supported algorithms
 246                      include md5, sha1, sha224, sha256, sha384, and sha512.
 247   --md5sum           Display the MD5 hash of each file as it is read from
 248                      Keep.
 249   -n                 Do not write any data -- just read from Keep, and report
 250                      md5sums if requested.
 251   -r                 Retrieve all files in the specified collection/prefix.
 252                      This is the default behavior if the "locator" argument
 253                      ends with a forward slash.
 254   -f                 Overwrite existing files while writing. The default
 255                      behavior is to refuse to write *anything* if any of the
 256                      output files already exist. As a special case, -f is not
 257                      needed to write to stdout.
 258   -v                 Once for verbose mode, twice for debug mode.
 259   --skip-existing    Skip files that already exist. The default behavior is
 260                      to refuse to write *anything* if any files exist that
 261                      would have to be overwritten. This option causes even
 262                      devices, sockets, and fifos to be skipped.
 263   --strip-manifest   When getting a collection manifest, strip its access
 264                      tokens before writing it.
 265   --threads N        Set the number of download threads to be used. Take into
 266                      account that using lots of threads will increase the RAM
 267                      requirements. Default is to use 4 threads. On high
 268                      latency installations, using a greater number will
 269                      improve overall throughput.
 270 </pre>
 271 </notextile>
 272
 273 h3(#arv-keep-put). arv keep put
 274
 275 This is a frontend to @arv-put@.
 276
 277 <notextile>
 278 <pre>
 279 $ <code class="userinput">arv keep put --help</code>
 280 usage: arv-put [-h] [--max-manifest-depth N | --normalize]
 281                [--as-stream | --stream | --as-manifest | --in-manifest | --manifest | --as-raw | --raw]
 282                [--use-filename FILENAME] [--filename FILENAME]
 283                [--portable-data-hash] [--replication N]
 284                [--project-uuid UUID] [--name NAME]
 285                [--progress | --no-progress | --batch-progress]
 286                [--resume | --no-resume] [--retries RETRIES]
 287                [path [path ...]]
 288
 289 Copy data from the local filesystem to Keep.
 290
 291 positional arguments:
 292   path                  Local file or directory. Default: read from standard
 293                         input.
 294
 295 optional arguments:
 296   -h, --help            show this help message and exit
 297   --max-manifest-depth N
 298                         Maximum depth of directory tree to represent in the
 299                         manifest structure. A directory structure deeper than
 300                         this will be represented as a single stream in the
 301                         manifest. If N=0, the manifest will contain a single
 302                         stream. Default: -1 (unlimited), i.e., exactly one
 303                         manifest stream per filesystem directory that contains
 304                         files.
 305   --normalize           Normalize the manifest by re-ordering files and
 306                         streams after writing data.
 307   --as-stream           Synonym for --stream.
 308   --stream              Store the file content and display the resulting
 309                         manifest on stdout. Do not write the manifest to Keep
 310                         or save a Collection object in Arvados.
 311   --as-manifest         Synonym for --manifest.
 312   --in-manifest         Synonym for --manifest.
 313   --manifest            Store the file data and resulting manifest in Keep,
 314                         save a Collection object in Arvados, and display the
 315                         manifest locator (Collection uuid) on stdout. This is
 316                         the default behavior.
 317   --as-raw              Synonym for --raw.
 318   --raw                 Store the file content and display the data block
 319                         locators on stdout, separated by commas, with a
 320                         trailing newline. Do not store a manifest.
 321   --use-filename FILENAME
 322                         Synonym for --filename.
 323   --filename FILENAME   Use the given filename in the manifest, instead of the
 324                         name of the local file. This is useful when "-" or
 325                         "/dev/stdin" is given as an input file. It can be used
 326                         only if there is exactly one path given and it is not
 327                         a directory. Implies --manifest.
 328   --portable-data-hash  Print the portable data hash instead of the Arvados
 329                         UUID for the collection created by the upload.
 330   --replication N       Set the replication level for the new collection: how
 331                         many different physical storage devices (e.g., disks)
 332                         should have a copy of each data block. Default is to
 333                         use the server-provided default (if any) or 2.
 334   --project-uuid UUID   Store the collection in the specified project, instead
 335                         of your Home project.
 336   --name NAME           Save the collection with the specified name.
 337   --progress            Display human-readable progress on stderr (bytes and,
 338                         if possible, percentage of total data size). This is
 339                         the default behavior when stderr is a tty.
 340   --no-progress         Do not display human-readable progress on stderr, even
 341                         if stderr is a tty.
 342   --batch-progress      Display machine-readable progress on stderr (bytes
 343                         and, if known, total data size).
 344   --resume              Continue interrupted uploads from cached state
 345                         (default).
 346   --no-resume           Do not continue interrupted uploads from cached state.
 347   --retries RETRIES     Maximum number of times to retry server requests that
 348                         encounter temporary failures (e.g., server down).
 349                         Default 3.
 350 </pre>
 351 </notextile>