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