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 The @arv@ CLI tool provides access to a number of subcommands which are described on this page.
  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 arvados cli client
 101   --dry-run, -n:   Don't actually do anything
 102   --verbose, -v:   Print some things on stderr
 103      --uuid, -u:   Return the UUIDs of the objects in the response, one per
 104                    line (default)
 105      --json, -j:   Return the entire response received from the API server, as
 106                    a JSON object
 107     --human, -h:   Return the response received from the API server, as a JSON
 108                    object with whitespace added for human consumption
 109    --pretty, -p:   Synonym of --human
 110      --yaml, -y:   Return the response received from the API server, in YAML
 111                    format
 112      --help, -e:   Show this message
 113 </pre>
 114 </notextile>
 115
 116
 117 h3(#arv-ws). arv ws
 118
 119 @arv ws@ provides access to the websockets event stream.
 120
 121 <notextile>
 122 <pre>
 123 $ <code class="userinput">arv ws --help</code>
 124 usage: arv-ws [-h] [-u UUID] [-f FILTERS]
 125               [--poll-interval POLL_INTERVAL | --no-poll]
 126               [-p PIPELINE | -j JOB]
 127
 128 optional arguments:
 129   -h, --help            show this help message and exit
 130   -u UUID, --uuid UUID  Filter events on object_uuid
 131   -f FILTERS, --filters FILTERS
 132                         Arvados query filter to apply to log events (JSON
 133                         encoded)
 134   --poll-interval POLL_INTERVAL
 135                         If websockets is not available, specify the polling
 136                         interval, default is every 15 seconds
 137   --no-poll             Do not poll if websockets are not available, just fail
 138   -p PIPELINE, --pipeline PIPELINE
 139                         Supply pipeline uuid, print log output from pipeline
 140                         and its jobs
 141   -j JOB, --job JOB     Supply job uuid, print log output from jobs
 142 </pre>
 143 </notextile>
 144
 145 h3(#arv-keep). arv keep
 146
 147 @arv keep@ provides access to the Keep storage service.
 148
 149 <notextile>
 150 <pre>
 151 $ <code class="userinput">arv keep --help</code>
 152 Usage: arv keep [method] [--parameters]
 153 Use 'arv keep [method] --help' to get more information about specific methods.
 154
 155 Available methods: ls, get, put, less, check, docker
 156 </pre>
 157 </notextile>
 158
 159 h3(#arv-pipeline-run). arv pipeline run
 160
 161 @arv pipeline run@ can be used to start a pipeline run from the command line.
 162
 163 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.
 164
 165 <notextile>
 166 <pre>
 167 $ <code class="userinput">arv pipeline run --help</code>
 168 Options:
 169         --dry-run, -n:   Do not start any new jobs or wait for existing jobs to
 170                          finish. Just find out whether jobs are finished,
 171                          queued, or running for each component.
 172     --status-text &lt;s&gt;:   Store plain text status in given file. (Default:
 173                          /dev/stdout)
 174     --status-json &lt;s&gt;:   Store json-formatted pipeline in given file. (Default:
 175                          /dev/null)
 176             --no-wait:   Do not wait for jobs to finish. Just look up status,
 177                          submit new jobs if needed, and exit.
 178            --no-reuse:   Do not reuse existing jobs to satisfy pipeline
 179                          components. Submit a new job for every component.
 180           --debug, -d:   Print extra debugging information on stderr.
 181     --debug-level &lt;i&gt;:   Set debug verbosity level.
 182        --template &lt;s&gt;:   UUID of pipeline template, or path to local pipeline
 183                          template file.
 184        --instance &lt;s&gt;:   UUID of pipeline instance.
 185              --submit:   Submit the pipeline instance to the server, and exit.
 186                          Let the Crunch dispatch service satisfy the components
 187                          by finding/running jobs.
 188   --run-pipeline-here:   Manage the pipeline instance in-process. Submit jobs
 189                          to Crunch as needed. Do not exit until the pipeline
 190                          finishes (or fails).
 191       --run-jobs-here:   Run jobs in the local terminal session instead of
 192                          submitting them to Crunch. Implies
 193                          --run-pipeline-here. Note: this results in a
 194                          significantly different job execution environment, and
 195                          some Crunch features are not supported. It can be
 196                          necessary to modify a pipeline in order to make it run
 197                          this way.
 198            --run-here:   Synonym for --run-jobs-here.
 199     --description &lt;s&gt;:   Description for the pipeline instance.
 200         --version, -v:   Print version and exit
 201            --help, -h:   Show this message
 202 </pre>
 203 </notextile>
 204
 205 h3(#arv-run). arv run
 206
 207 The @arv-run@ command creates Arvados pipelines at the command line that fan out to multiple concurrent tasks across Arvado compute nodes.
 208
 209 The User Guide has a page on "using arv-run":{{site.baseurl}}/user/topics/arv-run.html.
 210
 211 <notextile>
 212 <pre>
 213 $ <code class="userinput">arv run --help</code>
 214 usage: arv-run [-h] [--retries RETRIES] [--dry-run] [--local]
 215                [--docker-image DOCKER_IMAGE] [--ignore-rcode] [--no-reuse]
 216                [--no-wait] [--project-uuid PROJECT_UUID] [--git-dir GIT_DIR]
 217                [--repository REPOSITORY] [--script-version SCRIPT_VERSION]
 218                ...
 219
 220 positional arguments:
 221   args
 222
 223 optional arguments:
 224   -h, --help            show this help message and exit
 225   --retries RETRIES     Maximum number of times to retry server requests that
 226                         encounter temporary failures (e.g., server down).
 227                         Default 3.
 228   --dry-run             Print out the pipeline that would be submitted and
 229                         exit
 230   --local               Run locally using arv-run-pipeline-instance
 231   --docker-image DOCKER_IMAGE
 232                         Docker image to use, default arvados/jobs
 233   --ignore-rcode        Commands that return non-zero return codes should not
 234                         be considered failed.
 235   --no-reuse            Do not reuse past jobs.
 236   --no-wait             Do not wait and display logs after submitting command,
 237                         just exit.
 238   --project-uuid PROJECT_UUID
 239                         Parent project of the pipeline
 240   --git-dir GIT_DIR     Git repository passed to arv-crunch-job when using
 241                         --local
 242   --repository REPOSITORY
 243                         repository field of component, default 'arvados'
 244   --script-version SCRIPT_VERSION
 245                         script_version field of component, default 'master'
 246 </pre>
 247 </notextile>
 248