Skip to content

Commit 29425ef

Browse files
lbergelsonlbergelson
authored
improve documentation (#26)
* updating the command line documentation and README * help now includes descriptions of what the commands and arguments are as well as some examples
1 parent 5dc58b3 commit 29425ef

File tree

2 files changed

+90
-45
lines changed

2 files changed

+90
-45
lines changed

‎README.md

Lines changed: 52 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,63 @@
55
Alternatively, download the script and put it somewhere...
66

77
# cromshell
8-
shell script for interacting with cromwell servers
8+
A script for submitting workflows to a cromwell server and monitoring / querying their results.
99

10-
requires `curl`, `mail`, and [jq](https://stedolan.github.io/jq/)
10+
requires `column`, `curl`, `mail`, and [jq](https://stedolan.github.io/jq/)
11+
12+
### Examples:
13+
14+
```
15+
cromshell submit workflow.wdl inputs.json options.json dependencies.zip
16+
cromshell status
17+
cromshell logs -2
18+
```
1119

1220
### Supported Subcommands:
13-
* `submit` [wdl-file] [inputs] [options] [dependencies]
14-
* `status` [worfklow-id] [[worfklow-id]...]
15-
* `logs` [worfklow-id] [[worfklow-id]...]
16-
* `metadata` [worfklow-id] [[worfklow-id]...]
17-
* `slim-metadata` [worfklow-id] [[worfklow-id]...]
18-
* `execution-status-count` [worfklow-id] [[worfklow-id]...]
19-
* `timing` [worfklow-id] [[worfklow-id]...]
20-
* `abort` [worfklow-id] [[worfklow-id]...]
21-
* `notify` [workflow-id] [server_to_run_daemon] email_address
21+
22+
23+
#### Start/Stop workflows
24+
* `submit` *`workflow.wdl`* *`inputs.json`* `[options json]` `[included wdls]`
25+
* Submit a new workflow
26+
* `abort` *`[workflow-id] [[workflow-id]...]`*
27+
* Abort a running workflow
28+
#### Query workflow status:
29+
* `status` *`[workflow-id] [[workflow-id]...]`*
30+
* Check the status of a workflow
31+
* `metadata` *`[workflow-id] [[workflow-id]...]`*
32+
* Get the full metadata of a workflow
33+
* `slim-metadata` *`[workflow-id] [[workflow-id]...]`*
34+
* Get a subset of the metadata from a workflow
35+
* `execution-status-count` *`[workflow-id] [[workflow-id]...]`*
36+
* Get the summarized status of all jobs in the workflow
37+
* `timing` *`[workflow-id] [[workflow-id]...]`*
38+
* Open the timing diagram in a browser
39+
40+
#### Logs
41+
* `logs` *`[workflow-id] [[workflow-id]...]`*
42+
* List the log files produced by a workflow
43+
* `fetch-logs` *`[workflow-id] [[workflow-id]...]`*
44+
* Download all logs produced by a workflow
45+
46+
#### Job Outputs
47+
* `list-outputs` *`[workflow-id] [[workflow-id]...]`*
48+
* List all output files produced by a workflow
49+
* `fetch-all` *`[workflow-id] [[workflow-id]...]`*
50+
* Download all output files produced by a workflow
51+
52+
#### Get email notification on job completion
53+
* `notify` *`[workflow-id]` `[daemon-server]` `email` `[cromwell-server]`*
54+
* *`daemon-server`* server to run the notification daemon on
55+
56+
#### Display a list jobs submitted through cromshell
57+
* `list` *`[-c]` `[-u]`*
58+
* *`-c`* Color the output by completion status
59+
* *`-u`* Check completion status of all unfinished jobs
2260

2361
### Features:
24-
* Running `submit` will create a new folder in your working directory named with the cromwell job id of the newly submitted job.
62+
* Running `submit` will create a new folder in the `~/.cromshell/${CROMWELL_URL}/` directory named with the cromwell job id of the newly submitted job.
2563
It will copy your wdl and json inputs into the folder for reproducibility.
2664
* It keeps track of your most recently submitted jobs by storing their ids in `./cromshell/`
2765
You may ommit the job ID of the last job submitted when running commands, or use negative numbers to reference previous jobs, e.g. "-1" will track the last job, "-2" will track the one before that, and so on.
28-
* You can override the default cromwell server by setting the environmental variable CROMWELL_URL to the appropriate URL.
29-
* The commands `status` and `abort` takes multiple workflow-id's, but only accepts the explicit ids when multiple ids are provided, i.e. `./cromwell status -1 -2 -3` won't work.
66+
* You can override the default cromwell server by setting the environmental variable `CROMWELL_URL` to the appropriate URL.
67+
* Most commands takes multiple workflow-id's, but only accepts the explicit ids when multiple ids are provided, i.e. `./cromwell status -1 -2 -3` won't work.

‎cromshell

Lines changed: 38 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -62,47 +62,52 @@ OPTIONS=''
6262
function simpleUsage()
6363
{
6464
echo -e "Usage: ${SCRIPTNAME} <subcommand> [options]"
65-
echo -e "Pokes Cromwell REST endpoints at a server specified by the "
66-
echo -e "environment variable \$CROMWELL_URL"
65+
echo -e "Run and inspect workflows on a Cromwell server."
6766
}
6867

6968
#Define a usage function:
7069
function usage()
7170
{
7271
simpleUsage
72+
echo -e "CROMWELL_URL=$CROMWELL_URL"
7373
echo
74-
echo -e "When submitting a workflow, the returned worfklow-id will become the"
75-
echo -e "last used workflow id. Also, you can use -n instead of a workflow-id to "
76-
echo -e "use a previous run (status -1 would be the status of the last run,"
77-
echo -e "-2 would be the one before that). However, for commands that "
78-
echo -e "accepts multiple workflow-id's (status and abort), this does not apply, "
79-
echo -e "the explicit workflow-id's are expected if you provide multiple ones."
74+
echo -e "If no workflow-id is specified then the last submitted workflow-id is assumed."
75+
echo -e "Alternatively, negative numbers can be used to refer to previous workflows."
8076
echo
81-
echo -e "NOTE: As a convenience, if you omit a workflow-id from a command,"
82-
echo -e "the last used workflow-id will be used as a default. "
77+
echo -e " example usage:"
78+
echo -e " cromshell submit workflow.wdl inputs.json options.json dependencies.zip"
79+
echo -e " cromshell status"
80+
echo -e " cromshell logs -2"
8381
echo
84-
if [[ ${#PREREQUISITES} -ne 0 ]] ; then
85-
echo -e "Requires the following programs to be installed:"
86-
for prereq in ${PREREQUISITES} ; do
87-
echo -e " ${prereq}"
88-
done
89-
echo
90-
fi
9182
echo -e "Supported Subcommands:"
92-
echo -e " submit [wdl-file] [inputs] [options] [dependencies]"
93-
echo -e " status [worfklow-id] [[worfklow-id]...]"
94-
echo -e " logs [worfklow-id] [[worfklow-id]...]"
95-
echo -e " metadata [worfklow-id] [[worfklow-id]...]"
96-
echo -e " slim-metadata [worfklow-id] [[worfklow-id]...]"
97-
echo -e " execution-status-count [worfklow-id] [[worfklow-id]...]"
98-
echo -e " timing [worfklow-id] [[worfklow-id]...]"
99-
echo -e " abort [worfklow-id] [[worfklow-id]...]"
100-
echo -e " notify [workflow-id] [server_to_run_daemon] email_address [cromwell_server]"
101-
echo -e " fetch-logs [workflow-id] [[workflow-id]...]"
102-
echo -e " fetch-all [workflow-id] [[workflow-id]...]"
103-
echo -e " list-outputs [workflow-id] [[workflow-id]...]"
104-
echo -e " list [-c] [-u]"
105-
echo
83+
echo -e " Start/Stop workflows"
84+
echo -e " submit <wdl> <inputs json> [options json] [included wdls] Submit a new workflow"
85+
echo -e " abort [workflow-id] [[workflow-id]...] Abort a running workflow"
86+
echo -e
87+
echo -e " Query workflow status:"
88+
echo -e " status [workflow-id] [[workflow-id]...] Check the status of a workflow"
89+
echo -e " metadata [workflow-id] [[workflow-id]...] Get the full metadata of a workflow"
90+
echo -e " slim-metadata [workflow-id] [[workflow-id]...] Get a subset of the metadata from a workflow"
91+
echo -e " execution-status-count [workflow-id] [[workflow-id]...] Get the summarized status of all jobs in the workflow"
92+
echo -e " timing [workflow-id] [[workflow-id]...] Open the timing diagram in a browser"
93+
echo -e
94+
echo -e " Logs"
95+
echo -e " logs [workflow-id] [[workflow-id]...] List the log files produced by a workflow"
96+
echo -e " fetch-logs [workflow-id] [[workflow-id]...] Download all logs produced by a workflow"
97+
echo -e
98+
echo -e " Job Outputs"
99+
echo -e " list-outputs [workflow-id] [[workflow-id]...] List all output files produced by a workflow"
100+
echo -e " fetch-all [workflow-id] [[workflow-id]...] Download all output files produced by a workflow"
101+
echo -e
102+
echo " Get email notification on job completion"
103+
echo -e " notify [workflow-id] [daemon-server] email [cromwell-server]"
104+
echo -e " daemon-server server to run the notification daemon on"
105+
echo
106+
echo -e " Display a list jobs submitted through cromshell:"
107+
echo -e " list [-c] [-u] "
108+
echo -e " -c Color the output by completion status"
109+
echo -e " -u Check completion status of all unfinished jobs"
110+
echo -e
106111
echo -e "Return values:"
107112
echo -e " 0 SUCCESS"
108113
echo -e " ANYTHING_BUT_ZERO FAILURE/ERROR"
@@ -235,8 +240,10 @@ function populateWorkflowIdAndServerUrl()
235240
}
236241

237242
# Submit a workflow and arguments to the Cromwell Server
243+
238244
function submit()
239245
{
246+
240247
local response=$(curl --connect-timeout $CURL_CONNECT_TIMEOUT -s -F workflowSource=@${1} ${2:+ -F workflowInputs=@${2}} ${3:+ -F workflowOptions=@${3}} ${4:+ -F workflowDependencies=@${4}} ${CROMWELL_URL}/api/workflows/v1)
241248
local r=$?
242249
echo $response

0 commit comments

Comments
 (0)