doc/user/cwl/cwl-run-options.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "arvados-cwl-runner options"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 # "*Command line options*":#options
  13 # "*Specify workflow and output names*":#names
  14 # "*Submit a workflow without waiting for the result*":#nowait
  15 # "*Control a workflow locally*":#local
  16 # "*Automatically delete intermediate outputs*":#delete
  17 # "*Run workflow on a remote federated cluster*":#federation
  18
  19 h3(#options). Command line options
  20
  21 The following command line options are available for @arvados-cwl-runner@:
  22
  23 table(table table-bordered table-condensed).
  24 |_. Option |_. Description |
  25 |==--basedir== BASEDIR|     Base directory used to resolve relative references in the input, default to directory of input object file or current directory (if inputs piped/provided on command line).|
  26 |==--eval-timeout EVAL_TIMEOUT==|Time to wait for a Javascript expression to evaluate before giving an error, default 20s.|
  27 |==--print-dot==|           Print workflow visualization in graphviz format and exit|
  28 |==--version==|             Print version and exit|
  29 |==--validate==|            Validate CWL document only.|
  30 |==--verbose==|             Default logging|
  31 |==--quiet==|               Only print warnings and errors.|
  32 |==--debug==|               Print even more logging|
  33 |==--metrics==|             Print timing metrics|
  34 |==--tool-help==|           Print command line help for tool|
  35 |==--enable-reuse==|        Enable container reuse (default)|
  36 |==--disable-reuse==|       Disable container reuse|
  37 |==--project-uuid UUID==|   Project that will own the workflow containers, if not provided, will go to home project.|
  38 |==--output-name OUTPUT_NAME==|Name to use for collection that stores the final output.|
  39 |==--output-tags OUTPUT_TAGS==|Tags for the final output collection separated by commas, e.g., =='--output-tags tag0,tag1,tag2'==.|
  40 |==--ignore-docker-for-reuse==|Ignore Docker image version when deciding whether to reuse past containers.|
  41 |==--submit==|              Submit workflow runner to Arvados to manage the workflow (default).|
  42 |==--local==|               Run workflow on local host (still submits containers to Arvados).|
  43 |==--create-template==|     (Deprecated) synonym for --create-workflow.|
  44 |==--create-workflow==|     Register an Arvados workflow that can be run from Workbench|
  45 |==--update-workflow== UUID|Update an existing Arvados workflow or pipeline template with the given UUID.|
  46 |==--wait==|                After submitting workflow runner, wait for completion.|
  47 |==--no-wait==|             Submit workflow runner and exit.|
  48 |==--log-timestamps==|      Prefix logging lines with timestamp|
  49 |==--no-log-timestamps==|   No timestamp on logging lines|
  50 |==--compute-checksum==|    Compute checksum of contents while collecting outputs|
  51 |==--submit-runner-ram== SUBMIT_RUNNER_RAM|RAM (in MiB) required for the workflow runner (default 1024)|
  52 |==--submit-runner-image== SUBMIT_RUNNER_IMAGE|Docker image for workflow runner|
  53 |==--always-submit-runner==|When invoked with --submit --wait, always submit a runner to manage the workflow, even when only running a single CommandLineTool|
  54 |==--match-submitter-images==|Where Arvados has more than one Docker image of the same name, use image from the Docker instance on the submitting node.|
  55 |==--submit-request-uuid== UUID|Update and commit to supplied container request instead of creating a new one.|
  56 |==--submit-runner-cluster== CLUSTER_ID|Submit workflow runner to a remote cluster|
  57 |==--name NAME==|Name to use for workflow execution instance.|
  58 |==--on-error== {stop,continue}|Desired workflow behavior when a step fails.  One of 'stop' (do not submit any more steps) or 'continue' (may submit other steps that are not downstream from the error). Default is 'continue'.|
  59 |==--enable-dev==|Enable loading and running development versions of CWL spec.|
  60 |==--storage-classes== STORAGE_CLASSES|Specify comma separated list of storage classes to be used when saving the final workflow output to Keep.|
  61 |==--intermediate-storage-classes== STORAGE_CLASSES|Specify comma separated list of storage classes to be used when intermediate workflow output to Keep.|
  62 |==--intermediate-output-ttl== N|If N > 0, intermediate output collections will be trashed N seconds after creation. Default is 0 (don't trash).|
  63 |==--priority== PRIORITY|Workflow priority (range 1..1000, higher has precedence over lower)|
  64 |==--thread-count== THREAD_COUNT|Number of threads to use for container submit and output collection.|
  65 |==--http-timeout== HTTP_TIMEOUT|API request timeout in seconds. Default is 300 seconds (5 minutes).|
  66 |==--enable-preemptible==|Use preemptible instances. Control individual steps with "arv:UsePreemptible":cwl-extensions.html#UsePreemptible hint.|
  67 |==--disable-preemptible==|Don't use preemptible instances.|
  68 |==--skip-schemas==|Skip loading of extension schemas (the $schemas section).|
  69 |==--trash-intermediate==|Immediately trash intermediate outputs on workflow success.|
  70 |==--no-trash-intermediate==|Do not trash intermediate outputs (default).|
  71
  72
  73 h3(#names). Specify workflow and output names
  74
  75 Use the @--name@ and @--output-name@ options to specify the name of the workflow and name of the output collection.
  76
  77 <notextile>
  78 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --name "Example bwa run" --output-name "Example bwa output" bwa-mem.cwl bwa-mem-input.yml</span>
  79 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
  80 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
  81 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to zzzzz-4zz18-h7ljh5u76760ww2
  82 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
  83 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Running
  84 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-fm2n3b1w0l6bskg) is Complete
  85 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
  86 {
  87     "aligned_sam": {
  88         "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
  89         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
  90         "class": "File",
  91         "size": 30738986
  92     }
  93 }
  94 </code></pre>
  95 </notextile>
  96
  97 h3(#nowait). Submit a workflow without waiting for the result
  98
  99 To submit a workflow and exit immediately, use the @--no-wait@ option.  This will submit the workflow to Arvados, print out the UUID of the job that was submitted to standard output, and exit.
 100
 101 <notextile>
 102 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
 103 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 104 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
 105 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to zzzzz-4zz18-eqnfwrow8aysa9q
 106 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job zzzzz-8i9sb-fm2n3b1w0l6bskg
 107 zzzzz-8i9sb-fm2n3b1w0l6bskg
 108 </code></pre>
 109 </notextile>
 110
 111 h3(#local). Control a workflow locally
 112
 113 To run a workflow with local control, use @--local@.  This means that the host where you run @arvados-cwl-runner@ will be responsible for submitting containers, however, the containers themselves will still run on the Arvados cluster.  With @--local@, if you interrupt @arvados-cwl-runner@ or log out, the workflow will be terminated.
 114
 115 <notextile>
 116 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
 117 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
 118 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance zzzzz-d1hrv-92wcu6ldtio74r4
 119 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-2nzzfbuf9zjrj4g) is Queued
 120 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-2nzzfbuf9zjrj4g) is Running
 121 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (zzzzz-8i9sb-2nzzfbuf9zjrj4g) is Complete
 122 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
 123 {
 124     "aligned_sam": {
 125         "size": 30738986,
 126         "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
 127         "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
 128         "class": "File"
 129     }
 130 }
 131 </code></pre>
 132 </notextile>
 133
 134 h3(#delete). Automatically delete intermediate outputs
 135
 136 Use the @--intermediate-output-ttl@ and @--trash-intermediate@ options to specify how long intermediate outputs should be kept (in seconds) and whether to trash them immediately upon successful workflow completion.
 137
 138 Temporary collections will be trashed @intermediate-output-ttl@ seconds after creation.  A value of zero (default) means intermediate output should be retained indefinitely.
 139
 140 Note: arvados-cwl-runner currently does not take workflow dependencies into account when setting the TTL on an intermediate output collection. If the TTL is too short, it is possible for a collection to be trashed before downstream steps that consume it are started.  The recommended minimum value for TTL is the expected duration for the entire the workflow.
 141
 142 Using @--trash-intermediate@ without @--intermediate-output-ttl@ means that intermediate files will be trashed on successful completion, but will remain on workflow failure.
 143
 144 Using @--intermediate-output-ttl@ without @--trash-intermediate@ means that intermediate files will be trashed only after the TTL expires (regardless of workflow success or failure).
 145
 146 h3(#federation). Run workflow on a remote federated cluster
 147
 148 By default, the workflow runner will run on the local (home) cluster.  Using @--submit-runner-cluster@ you can specify that the runner should be submitted to a remote federated cluster.  When doing this, @--project-uuid@ should specify a project on that cluster.  Steps making up the workflow will be submitted to the remote federated cluster by default, but the behavior of @arv:ClusterTarget@ is unchanged.  Note: when using this option, any resources that need to be uploaded in order to run the workflow (such as files or Docker images) will be uploaded to the local (home) cluster, and streamed to the federated cluster on demand.
 149
 150 h3(#preemptible). Using preemptible (spot) instances
 151
 152 Preemptible instances typically offer lower cost computation with a tradeoff of lower service guarantees.  If a compute node is preempted, Arvados will restart the computation on a new instance.
 153
 154 If the sitewide configuration @Containers.AlwaysUsePreemptibleInstances@ is true, workflow steps will always select preemptible instances, regardless of user option.
 155
 156 If @Containers.AlwaysUsePreemptibleInstances@ is false, you can request preemptible instances for a specific run with the @arvados-cwl-runner --enable-preemptible@ option.
 157
 158 Within the workflow, you can control whether individual steps should be preemptible with the "arv:UsePreemptible":cwl-extensions.html#UsePreemptible hint.
 159
 160 If a workflow requests preemptible instances with "arv:UsePreemptible":cwl-extensions.html#UsePreemptible , but you _do not_ want to use preemptible instances, you can override it for a specific run with the @arvados-cwl-runner --disable-preemptible@ option.
 161
 162 h3(#gpu). Use CUDA GPU instances
 163
 164 See "cwltool:CUDARequirement":cwl-extensions.html#CUDARequirement .