Use the Command Line¶
This page shows how to send tasks to a GA4GH TES service in
ELIXIR On-Cloud from your terminal with ga4gh-cli, the command-line tool of
the GA4GH SDK. The tool is at an early
stage and has no releases yet. This page describes what it does today,
including what it can't do yet.
What the CLI can't do yet
- No authentication: the CLI doesn't send an access token or any other credentials, even if they are in its configuration file. It can't use a service that requires an LS Login token.
- No proTES: the CLI ignores the path in the service address, so it
can't reach a service that serves its API only at
/ga4gh/tes/v1, such as proTES. - No WES: the CLI has no commands for workflows.
Work without the CLI shows how to reach these
services with curl instead.
Install¶
The project publishes no binaries or packages, so you build the CLI from its source code. You need Git and Rust.
git clone https://github.com/ga4gh/ga4gh-sdk.git
cd ga4gh-sdk
git checkout 82432c3 # the commit that this page describes
cargo build
./target/debug/cli --version
The program is called cli, not ga4gh-cli as in the CLI's
README. You can
copy it to a directory on your PATH. The commands below use the name cli.
Build the whole project with cargo build, as shown. cargo build -p
ga4gh-cli and cargo install --path cli currently fail with a compile
error in commit 82432c3.
The build was tested on that commit in the rust:1 container image (Rust
1.99.1), which comes with the system libraries that the build uses. The
project has no lock file, so your build can pick newer dependencies.
Configure¶
The CLI reads the address of the service from ~/.ga4gh-cli/config.json:
- All three keys must be there: without
basic_authoroauth_access_token, the CLI stops with the errorno entry found for key. Set them tonull. base_path: use the scheme, the host and the port. The CLI ignores any path (see Which services work).- One service at a time: to use another service, edit the file. There are no profiles and no command-line option for the address.
- No file: without the file, the CLI uses
http://localhost.
Don't put credentials in the configuration file
The file also accepts a user name and password (basic_auth) and a token
(oauth_access_token). The CLI never sends them. Keep both set to null.
Which services work¶
The CLI calls these paths on the host of base_path:
| Command | Request |
|---|---|
all but status and cancel |
GET /service-info |
tes create |
POST /ga4gh/tes/v1/tasks |
tes list |
GET /tasks |
tes get, tes status |
GET /tasks/{id} |
tes cancel |
POST /tasks/{id}:cancel |
A service must answer at all these paths, without authentication, and its
service info must have the type tes. Funnel
does. A service that serves its API only at /ga4gh/tes/v1 answers 404 to
the first request, and the CLI reports Error accessing the service.
Send and manage tasks¶
Create a task¶
Write the task in a file, for example task.json. The TES
specification describes all fields.
Then send it:
The output is the ID of the new task and nothing else, so scripts can use it directly:
The argument must be a file: the CLI doesn't accept the JSON text directly, although its README shows that.
List tasks¶
| Option | What it does |
|---|---|
-n, --name_prefix |
Show only tasks whose name starts with this text. |
-s, --state |
Show only tasks in this state. Write the state with its double quotes: -s '"COMPLETE"'. Without them, the CLI crashes. |
-p, --page_size |
Ask for this number of tasks per page. |
-t, --page_token |
Ask for this page. The CLI doesn't show the token of the next page. |
-w, --view |
Send this view (MINIMAL, BASIC or FULL). The output stays the same. |
The options -k and -v (tags) are accepted, but ignored.
Get a task¶
The view is required: MINIMAL, BASIC or FULL. The CLI prints the task in
the internal format of the program, not as JSON.
Get the status of a task¶
Cancel a task¶
Check for errors¶
If the service answers tes create or tes list with an error, the CLI writes
the message to stderr, leaves stdout empty and still ends with the exit code
0. In scripts, check for empty stdout, not the exit code:
TASK_ID=$(cli tes create task.json)
if [ -z "$TASK_ID" ]; then
echo "The task was not created" >&2
exit 1
fi
This check also covers failures that do change the exit code: if the CLI can't
read the task file or reach the service, or if the service info is missing or
not of the type tes, it ends with the exit code 1 and stdout stays empty.
tes get works differently: it prints Err(...) to stdout, also with the exit
code 0, so look for that text in its output instead. tes status and
tes cancel report errors on stderr and end with the exit code 1.
Authentication¶
The CLI can't send a bearer token, such as an LS Login access token. No setting
changes this: the SDK reads the values from the file, but no request carries an
Authorization header. This also applies to the WES client of the SDK's Rust
library.
Work without the CLI¶
For a service that needs a token, get an access token as Using the
APIs describes, then
call the API with curl. Replace <HOST> with the address of the service, and
ask its operators which tokens they accept.
unset TOKEN # so that the token can't stay exported to other programs
read -rs TOKEN # paste the token; it is not shown or saved in the history
With --fail-with-body, curl shows the answer of the service and ends with
an error code if the service reports an error.
Send a task to a TES service such as proTES:
printf 'Authorization: Bearer %s\n' "$TOKEN" | curl --fail-with-body -X POST "https://<HOST>/ga4gh/tes/v1/tasks" -H @- -H 'Content-Type: application/json' -d @task.json
Read the task:
printf 'Authorization: Bearer %s\n' "$TOKEN" | curl --fail-with-body "https://<HOST>/ga4gh/tes/v1/tasks/<TASK_ID>?view=BASIC" -H @-
Send a workflow to a WES service. The path and the supported workflow types depend on the service; the WES specification describes the fields.
printf 'Authorization: Bearer %s\n' "$TOKEN" | curl --fail-with-body -X POST "https://<HOST>/ga4gh/wes/v1/runs" -H @- \
-F workflow_type=CWL \
-F workflow_type_version=v1.2 \
-F workflow_url=https://example.org/workflow.cwl \
-F 'workflow_params={}'
How this page was tested¶
We built the CLI at commit 82432c3 of the SDK and ran it in the rust:1
container image, on one computer:
- Funnel in a container, no authentication: all
tescommands reached the service, andtes createprinted only the ID. The test task ended inEXECUTOR_ERROR, because the container has no Docker to run it with, so no task was seen to finish. - Local mock service: it recorded the requests of the CLI. With a token and
a password in the configuration, none of them had an
Authorizationheader. With the API only at/ga4gh/tes/v1, as in proTES, the requests went to the wrong paths and failed. When it answered with errors, or when no service was listening, the CLI behaved as Check for errors describes, and the script there stopped. curl: the commands above were sent to the mock service over HTTP, not HTTPS, with the token passed toreadby a redirect instead of being pasted. The mock service recorded the token for all of them. It has no WES API and answered the workflow request with404.
We did not test against a deployed service, a real proTES or a real WES service, and we saw no task finish.
Where to go next¶
- The GA4GH SDK repository and the CLI's README. The project has no other user docs yet.
- Open requests for the SDK: WES commands, basic authentication and several service profiles.
- Questions: the Discussions or the About page.