4 title: "Using arvados-cwl-runner"
7 The following command line options are available for @arvados-cwl-runner@:
9 table(table table-bordered table-condensed).
10 |_. Option |_. Description |
11 |==--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).|
12 |==--version==| Print version and exit|
13 |==--validate==| Validate CWL document only.|
14 |==--verbose==| Default logging|
15 |==--quiet==| Only print warnings and errors.|
16 |==--debug==| Print even more logging|
17 |==--tool-help==| Print command line help for tool|
18 |==--enable-reuse==|Enable job reuse (default)|
19 |==--disable-reuse==|Disable job reuse (always run new jobs).|
20 |==--project-uuid UUID==| Project that will own the workflow jobs, if not provided, will go to home project.|
21 |==--output-name OUTPUT_NAME==|Name to use for collection that stores the final output.|
22 |==--output-tags OUTPUT_TAGS==|Tags for the final output collection separated by commas, e.g., =='--output-tags tag0,tag1,tag2'==.|
23 |==--ignore-docker-for-reuse==|Ignore Docker image version when deciding whether to reuse past jobs.|
24 |==--submit==| Submit workflow to run on Arvados.|
25 |==--local==| Control workflow from local host (submits jobs to Arvados).|
26 |==--create-template==| (Deprecated) synonym for ==--create-workflow.==|
27 |==--create-workflow==| Create an Arvados workflow (if using the 'containers' API) or pipeline template (if using the 'jobs' API). See ==--api==.|
28 |==--update-workflow== UUID|Update an existing Arvados workflow or pipeline template with the given UUID.|
29 |==--wait==| After submitting workflow runner job, wait for completion.|
30 |==--no-wait==| Submit workflow runner job and exit.|
31 |==--api== WORK_API| Select work submission API, one of 'jobs' or 'containers'. Default is 'jobs' if that API is available, otherwise 'containers'.|
32 |==--compute-checksum==| Compute checksum of contents while collecting outputs|
33 |==--submit-runner-ram== SUBMIT_RUNNER_RAM|RAM (in MiB) required for the workflow runner job (default 1024)|
34 |==--submit-runner-image== SUBMIT_RUNNER_IMAGE|Docker image for workflow runner job, default arvados/jobs|
35 |==--name== NAME| Name to use for workflow execution instance.|
36 |==--on-error {stop,continue}|Desired workflow behavior when a step fails. One of 'stop' or 'continue'. Default is 'continue'.|
37 |==--enable-dev==| Enable loading and running development versions of CWL spec.|
38 |==--intermediate-output-ttl== N|If N > 0, intermediate output collections will be trashed N seconds after creation. Default is 0 (don't trash).|
39 |==--trash-intermediate==| Immediately trash intermediate outputs on workflow success.|
40 |==--no-trash-intermediate==|Do not trash intermediate outputs (default).|
43 h3. Specify workflow and output names
45 Use the @--name@ and @--output-name@ options to specify the name of the workflow and name of the output collection.
48 <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>
49 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
50 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Upload local files: "bwa-mem.cwl"
51 2016-06-30 14:56:36 arvados.arv-run[27002] INFO: Uploaded to qr1hi-4zz18-h7ljh5u76760ww2
52 2016-06-30 14:56:40 arvados.cwl-runner[27002] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
53 2016-06-30 14:56:41 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Running
54 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-fm2n3b1w0l6bskg) is Complete
55 2016-06-30 14:57:12 arvados.cwl-runner[27002] INFO: Overall process status is success
58 "path": "keep:54325254b226664960de07b3b9482349+154/HWI-ST1027_129_D0THKACXX.1_1.sam",
59 "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
67 h3. Submit a workflow with no waiting
69 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.
72 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --no-wait bwa-mem.cwl bwa-mem-input.yml</span>
73 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
74 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Upload local files: "bwa-mem.cwl"
75 2016-06-30 15:07:52 arvados.arv-run[12480] INFO: Uploaded to qr1hi-4zz18-eqnfwrow8aysa9q
76 2016-06-30 15:07:52 arvados.cwl-runner[12480] INFO: Submitted job qr1hi-8i9sb-fm2n3b1w0l6bskg
77 qr1hi-8i9sb-fm2n3b1w0l6bskg
81 h3. Control a workflow locally
83 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 jobs, however, the jobs themselves will still run on the Arvados cluster. With @--local@, if you interrupt @arvados-cwl-runner@ or log out, the workflow will be terminated.
86 <pre><code>~/arvados/doc/user/cwl/bwa-mem$ <span class="userinput">arvados-cwl-runner --local bwa-mem.cwl bwa-mem-input.yml</span>
87 arvados-cwl-runner 1.0.20160628195002, arvados-python-client 0.1.20160616015107, cwltool 1.0.20160629140624
88 2016-07-01 10:05:19 arvados.cwl-runner[16290] INFO: Pipeline instance qr1hi-d1hrv-92wcu6ldtio74r4
89 2016-07-01 10:05:28 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Queued
90 2016-07-01 10:05:29 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Running
91 2016-07-01 10:05:45 arvados.cwl-runner[16290] INFO: Job bwa-mem.cwl (qr1hi-8i9sb-2nzzfbuf9zjrj4g) is Complete
92 2016-07-01 10:05:46 arvados.cwl-runner[16290] INFO: Overall process status is success
96 "path": "keep:15f56bad0aaa7364819bf14ca2a27c63+88/HWI-ST1027_129_D0THKACXX.1_1.sam",
97 "checksum": "sha1$0dc46a3126d0b5d4ce213b5f0e86e2d05a54755a",
104 h3. Automatically delete intermediate outputs
106 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.
108 Temporary collections will be trashed @intermediate-output-ttl@ seconds after creation. A value of zero (default) means intermediate output should be retained indefinitely.
110 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.
112 Using @--trash-intermediate@ without @--intermediate-output-ttl@ means that intermediate files will be trashed on successful completion, but will remain on workflow failure.
114 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).