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

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: CLI
   5 title: "arv subcommands"
   6
   7 ...
   8
   9 _In order to use the @arv@ command, make sure that you have a "working environment.":{{site.baseurl}}/user/getting_started/check-environment.html_
  10
  11 h3(#arv-create). arv create
  12
  13 @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.
  14
  15 <notextile>
  16 <pre>
  17 $ <code class="userinput">arv create --help</code>
  18 Options:
  19   --project-uuid, -p &lt;s&gt;:   Project uuid in which to create the object
  20               --help, -h:   Show this message
  21 </pre>
  22 </notextile>
  23
  24 h3(#arv-get). arv get
  25
  26 @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.
  27
  28 <notextile>
  29 <pre>
  30 $ <code class="userinput">arv get --help</code>
  31 Usage: arv [--format json|yaml] get [uuid] [fields...]
  32
  33 Fetch the specified Arvados object, select the specified fields,
  34 and print a text representation.
  35 </pre>
  36 </notextile>
  37
  38 h3(#arv-edit). arv edit
  39
  40 @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.
  41
  42 <notextile>
  43 <pre>
  44 $ <code class="userinput">arv edit --help</code>
  45 Arvados command line client
  46 Usage: arv edit [uuid] [fields...]
  47
  48 Fetch the specified Arvados object, select the specified fields,
  49 open an interactive text editor on a text representation (json or
  50 yaml, use --format) and then update the object.  Will use 'nano'
  51 by default, customize with the EDITOR or VISUAL environment variable.
  52 </pre>
  53 </notextile>
  54
  55 h3(#arv-copy). arv copy
  56
  57 @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.
  58
  59 <notextile>
  60 <pre>
  61 $ <code class="userinput">arv copy --help</code>
  62 usage: arv_copy.py [-h] [-v] [--progress] [--no-progress] [-f] --src
  63                    SOURCE_ARVADOS --dst DESTINATION_ARVADOS [--recursive]
  64                    [--no-recursive] [--dst-git-repo DST_GIT_REPO]
  65                    [--project-uuid PROJECT_UUID] [--retries RETRIES]
  66                    object_uuid
  67
  68 Copy a pipeline instance, template or collection from one Arvados instance to
  69 another.
  70
  71 positional arguments:
  72   object_uuid           The UUID of the object to be copied.
  73
  74 optional arguments:
  75   -h, --help            show this help message and exit
  76   -v, --verbose         Verbose output.
  77   --progress            Report progress on copying collections. (default)
  78   --no-progress         Do not report progress on copying collections.
  79   -f, --force           Perform copy even if the object appears to exist at
  80                         the remote destination.
  81   --src SOURCE_ARVADOS  The name of the source Arvados instance (required) -
  82                         points at an Arvados config file. May be either a
  83                         pathname to a config file, or (for example) "foo" as
  84                         shorthand for $HOME/.config/arvados/foo.conf.
  85   --dst DESTINATION_ARVADOS
  86                         The name of the destination Arvados instance
  87                         (required) - points at an Arvados config file. May be
  88                         either a pathname to a config file, or (for example)
  89                         "foo" as shorthand for $HOME/.config/arvados/foo.conf.
  90   --recursive           Recursively copy any dependencies for this object.
  91                         (default)
  92   --no-recursive        Do not copy any dependencies. NOTE: if this option is
  93                         given, the copied object will need to be updated
  94                         manually in order to be functional.
  95   --dst-git-repo DST_GIT_REPO
  96                         The name of the destination git repository. Required
  97                         when copying a pipeline recursively.
  98   --project-uuid PROJECT_UUID
  99                         The UUID of the project at the destination to which
 100                         the pipeline should be copied.
 101   --retries RETRIES     Maximum number of times to retry server requests that
 102                         encounter temporary failures (e.g., server down).
 103                         Default 3.
 104 </pre>
 105 </notextile>
 106
 107 h3(#arv-tag). arv tag
 108
 109 @arv tag@ is used to tag Arvados objects.
 110
 111 <notextile>
 112 <pre>
 113 $ <code class="userinput">arv tag --help</code>
 114
 115 Usage:
 116 arv tag add tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 117 arv tag remove tag1 [tag2 ...] --object object_uuid1 [object_uuid2...]
 118 arv tag remove --all
 119
 120   --dry-run, -n:   Don't actually do anything
 121   --verbose, -v:   Print some things on stderr
 122      --uuid, -u:   Return the UUIDs of the objects in the response, one per
 123                    line (default)
 124      --json, -j:   Return the entire response received from the API server, as
 125                    a JSON object
 126     --human, -h:   Return the response received from the API server, as a JSON
 127                    object with whitespace added for human consumption
 128    --pretty, -p:   Synonym of --human
 129      --yaml, -y:   Return the response received from the API server, in YAML
 130                    format
 131      --help, -e:   Show this message
 132 </pre>
 133 </notextile>
 134
 135
 136 h3(#arv-ws). arv ws
 137
 138 @arv ws@ provides access to the websockets event stream.
 139
 140 <notextile>
 141 <pre>
 142 $ <code class="userinput">arv ws --help</code>
 143 usage: arv-ws [-h] [-u UUID] [-f FILTERS]
 144               [--poll-interval POLL_INTERVAL | --no-poll]
 145               [-p PIPELINE | -j JOB]
 146
 147 optional arguments:
 148   -h, --help            show this help message and exit
 149   -u UUID, --uuid UUID  Filter events on object_uuid
 150   -f FILTERS, --filters FILTERS
 151                         Arvados query filter to apply to log events (JSON
 152                         encoded)
 153   --poll-interval POLL_INTERVAL
 154                         If websockets is not available, specify the polling
 155                         interval, default is every 15 seconds
 156   --no-poll             Do not poll if websockets are not available, just fail
 157   -p PIPELINE, --pipeline PIPELINE
 158                         Supply pipeline uuid, print log output from pipeline
 159                         and its jobs
 160   -j JOB, --job JOB     Supply job uuid, print log output from jobs
 161 </pre>
 162 </notextile>
 163
 164 h3(#arv-keep). arv keep
 165
 166 @arv keep@ provides access to the Keep storage service.
 167
 168 <notextile>
 169 <pre>
 170 $ <code class="userinput">arv keep --help</code>
 171 Usage: arv keep [method] [--parameters]
 172 Use 'arv keep [method] --help' to get more information about specific methods.
 173
 174 Available methods: ls, get, put, docker
 175 </pre>
 176 </notextile>
 177
 178 h3(#arv-keep-ls). arv keep ls
 179
 180 <notextile>
 181 <pre>
 182 $ <code class="userinput">arv keep ls --help</code>
 183 usage: arv-ls [-h] [--retries RETRIES] [-s] locator
 184
 185 List contents of a manifest
 186
 187 positional arguments:
 188   locator            Collection UUID or locator
 189
 190 optional arguments:
 191   -h, --help         show this help message and exit
 192   --retries RETRIES  Maximum number of times to retry server requests that
 193                      encounter temporary failures (e.g., server down). Default
 194                      3.
 195   -s                 List file sizes, in KiB.
 196 </pre>
 197 </notextile>
 198
 199 h3(#arv-keep-get). arv keep get
 200
 201 <notextile>
 202 <pre>
 203 $ <code class="userinput">arv keep get --help</code>
 204 usage: arv-get [-h] [--retries RETRIES]
 205                [--progress | --no-progress | --batch-progress]
 206                [--hash HASH | --md5sum] [-n] [-r] [-f | --skip-existing]
 207                locator [destination]
 208
 209 Copy data from Keep to a local file or pipe.
 210
 211 positional arguments:
 212   locator            Collection locator, optionally with a file path or
 213                      prefix.
 214   destination        Local file or directory where the data is to be written.
 215                      Default: /dev/stdout.
 216
 217 optional arguments:
 218   -h, --help         show this help message and exit
 219   --retries RETRIES  Maximum number of times to retry server requests that
 220                      encounter temporary failures (e.g., server down). Default
 221                      3.
 222   --progress         Display human-readable progress on stderr (bytes and, if
 223                      possible, percentage of total data size). This is the
 224                      default behavior when it is not expected to interfere
 225                      with the output: specifically, stderr is a tty _and_
 226                      either stdout is not a tty, or output is being written to
 227                      named files rather than stdout.
 228   --no-progress      Do not display human-readable progress on stderr.
 229   --batch-progress   Display machine-readable progress on stderr (bytes and,
 230                      if known, total data size).
 231   --hash HASH        Display the hash of each file as it is read from Keep,
 232                      using the given hash algorithm. Supported algorithms
 233                      include md5, sha1, sha224, sha256, sha384, and sha512.
 234   --md5sum           Display the MD5 hash of each file as it is read from
 235                      Keep.
 236   -n                 Do not write any data -- just read from Keep, and report
 237                      md5sums if requested.
 238   -r                 Retrieve all files in the specified collection/prefix.
 239                      This is the default behavior if the "locator" argument
 240                      ends with a forward slash.
 241   -f                 Overwrite existing files while writing. The default
 242                      behavior is to refuse to write *anything* if any of the
 243                      output files already exist. As a special case, -f is not
 244                      needed to write to /dev/stdout.
 245   --skip-existing    Skip files that already exist. The default behavior is to
 246                      refuse to write *anything* if any files exist that would
 247                      have to be overwritten. This option causes even devices,
 248                      sockets, and fifos to be skipped.
 249 </pre>
 250 </notextile>
 251
 252 h3(#arv-keep-put). arv keep put
 253
 254 <notextile>
 255 <pre>
 256 $ <code class="userinput">arv keep put --help</code>
 257 usage: arv-put [-h] [--max-manifest-depth N | --normalize]
 258                [--as-stream | --stream | --as-manifest | --in-manifest | --manifest | --as-raw | --raw]
 259                [--use-filename FILENAME] [--filename FILENAME]
 260                [--portable-data-hash] [--replication N]
 261                [--project-uuid UUID] [--name NAME]
 262                [--progress | --no-progress | --batch-progress]
 263                [--resume | --no-resume] [--retries RETRIES]
 264                [path [path ...]]
 265
 266 Copy data from the local filesystem to Keep.
 267
 268 positional arguments:
 269   path                  Local file or directory. Default: read from standard
 270                         input.
 271
 272 optional arguments:
 273   -h, --help            show this help message and exit
 274   --max-manifest-depth N
 275                         Maximum depth of directory tree to represent in the
 276                         manifest structure. A directory structure deeper than
 277                         this will be represented as a single stream in the
 278                         manifest. If N=0, the manifest will contain a single
 279                         stream. Default: -1 (unlimited), i.e., exactly one
 280                         manifest stream per filesystem directory that contains
 281                         files.
 282   --normalize           Normalize the manifest by re-ordering files and
 283                         streams after writing data.
 284   --as-stream           Synonym for --stream.
 285   --stream              Store the file content and display the resulting
 286                         manifest on stdout. Do not write the manifest to Keep
 287                         or save a Collection object in Arvados.
 288   --as-manifest         Synonym for --manifest.
 289   --in-manifest         Synonym for --manifest.
 290   --manifest            Store the file data and resulting manifest in Keep,
 291                         save a Collection object in Arvados, and display the
 292                         manifest locator (Collection uuid) on stdout. This is
 293                         the default behavior.
 294   --as-raw              Synonym for --raw.
 295   --raw                 Store the file content and display the data block
 296                         locators on stdout, separated by commas, with a
 297                         trailing newline. Do not store a manifest.
 298   --use-filename FILENAME
 299                         Synonym for --filename.
 300   --filename FILENAME   Use the given filename in the manifest, instead of the
 301                         name of the local file. This is useful when "-" or
 302                         "/dev/stdin" is given as an input file. It can be used
 303                         only if there is exactly one path given and it is not
 304                         a directory. Implies --manifest.
 305   --portable-data-hash  Print the portable data hash instead of the Arvados
 306                         UUID for the collection created by the upload.
 307   --replication N       Set the replication level for the new collection: how
 308                         many different physical storage devices (e.g., disks)
 309                         should have a copy of each data block. Default is to
 310                         use the server-provided default (if any) or 2.
 311   --project-uuid UUID   Store the collection in the specified project, instead
 312                         of your Home project.
 313   --name NAME           Save the collection with the specified name.
 314   --progress            Display human-readable progress on stderr (bytes and,
 315                         if possible, percentage of total data size). This is
 316                         the default behavior when stderr is a tty.
 317   --no-progress         Do not display human-readable progress on stderr, even
 318                         if stderr is a tty.
 319   --batch-progress      Display machine-readable progress on stderr (bytes
 320                         and, if known, total data size).
 321   --resume              Continue interrupted uploads from cached state
 322                         (default).
 323   --no-resume           Do not continue interrupted uploads from cached state.
 324   --retries RETRIES     Maximum number of times to retry server requests that
 325                         encounter temporary failures (e.g., server down).
 326                         Default 3.
 327 </pre>
 328 </notextile>
 329
 330
 331 h3(#arv-pipeline-run). arv pipeline run
 332
 333 @arv pipeline run@ can be used to start a pipeline run from the command line.
 334
 335 The User Guide has a page with a bit more information on "using arv pipeline run":{{site.baseurl}}/user/topics/running-pipeline-command-line.html.
 336
 337 <notextile>
 338 <pre>
 339 $ <code class="userinput">arv pipeline run --help</code>
 340 Options:
 341         --dry-run, -n:   Do not start any new jobs or wait for existing jobs to
 342                          finish. Just find out whether jobs are finished,
 343                          queued, or running for each component.
 344     --status-text &lt;s&gt;:   Store plain text status in given file. (Default:
 345                          /dev/stdout)
 346     --status-json &lt;s&gt;:   Store json-formatted pipeline in given file. (Default:
 347                          /dev/null)
 348             --no-wait:   Do not wait for jobs to finish. Just look up status,
 349                          submit new jobs if needed, and exit.
 350            --no-reuse:   Do not reuse existing jobs to satisfy pipeline
 351                          components. Submit a new job for every component.
 352           --debug, -d:   Print extra debugging information on stderr.
 353     --debug-level &lt;i&gt;:   Set debug verbosity level.
 354        --template &lt;s&gt;:   UUID of pipeline template, or path to local pipeline
 355                          template file.
 356        --instance &lt;s&gt;:   UUID of pipeline instance.
 357              --submit:   Submit the pipeline instance to the server, and exit.
 358                          Let the Crunch dispatch service satisfy the components
 359                          by finding/running jobs.
 360   --run-pipeline-here:   Manage the pipeline instance in-process. Submit jobs
 361                          to Crunch as needed. Do not exit until the pipeline
 362                          finishes (or fails).
 363       --run-jobs-here:   Run jobs in the local terminal session instead of
 364                          submitting them to Crunch. Implies
 365                          --run-pipeline-here. Note: this results in a
 366                          significantly different job execution environment, and
 367                          some Crunch features are not supported. It can be
 368                          necessary to modify a pipeline in order to make it run
 369                          this way.
 370            --run-here:   Synonym for --run-jobs-here.
 371     --description &lt;s&gt;:   Description for the pipeline instance.
 372         --version, -v:   Print version and exit
 373            --help, -h:   Show this message
 374 </pre>
 375 </notextile>
 376
 377 h3(#arv-run). arv run
 378
 379 The @arv-run@ command creates Arvados pipelines at the command line that fan out to multiple concurrent tasks across Arvados compute nodes.
 380
 381 The User Guide has a page on "using arv-run":{{site.baseurl}}/user/topics/arv-run.html.
 382
 383 <notextile>
 384 <pre>
 385 $ <code class="userinput">arv run --help</code>
 386 usage: arv-run [-h] [--retries RETRIES] [--dry-run] [--local]
 387                [--docker-image DOCKER_IMAGE] [--ignore-rcode] [--no-reuse]
 388                [--no-wait] [--project-uuid PROJECT_UUID] [--git-dir GIT_DIR]
 389                [--repository REPOSITORY] [--script-version SCRIPT_VERSION]
 390                ...
 391
 392 positional arguments:
 393   args
 394
 395 optional arguments:
 396   -h, --help            show this help message and exit
 397   --retries RETRIES     Maximum number of times to retry server requests that
 398                         encounter temporary failures (e.g., server down).
 399                         Default 3.
 400   --dry-run             Print out the pipeline that would be submitted and
 401                         exit
 402   --local               Run locally using arv-run-pipeline-instance
 403   --docker-image DOCKER_IMAGE
 404                         Docker image to use, otherwise use instance default.
 405   --ignore-rcode        Commands that return non-zero return codes should not
 406                         be considered failed.
 407   --no-reuse            Do not reuse past jobs.
 408   --no-wait             Do not wait and display logs after submitting command,
 409                         just exit.
 410   --project-uuid PROJECT_UUID
 411                         Parent project of the pipeline
 412   --git-dir GIT_DIR     Git repository passed to arv-crunch-job when using
 413                         --local
 414   --repository REPOSITORY
 415                         repository field of component, default 'arvados'
 416   --script-version SCRIPT_VERSION
 417                         script_version field of component, default 'master'
 418 </pre>
 419 </notextile>