GA4GH-CLI¶
The ga4gh-cli uses the GA4GH SDK to work with GA4GH API services. It
currently provides TES, WES, DRS, TRS and Service Registry commands, and a
service-info command for any configured service.
The Rust library also provides a ServiceInfo client (see the
usage guide).
Installation¶
Releases include ready-made binaries; see Download the CLI. To build from source, run from the repository root:
The CLI can also run as an OCI image for linux/amd64 and linux/arm64;
see the container image guide.
Configuration¶
The ga4gh-cli expects configuration in ~/.ga4gh-cli/config.json file.
The file and the section for the selected service (TES, WES, DRS, TRS
or REGISTRY) must exist;
the CLI reports an error instead of silently using http://localhost when
either is missing. Only base_path is required. basic_auth may omit
password, in which case no password is set.
Present authentication fields must have the documented types; malformed values
are errors rather than being ignored.
Configuration Example¶
{
"TES": {
"base_path": "http://localhost:8000/ga4gh/tes/v1"
},
"WES": {
"base_path": "https://wes.example.org/ga4gh/wes/v1",
"timeouts": {"discovery": 30, "submission": 600}
},
"DRS": {
"base_path": "https://drs.example.org/ga4gh/drs/v1"
},
"TRS": {
"base_path": "https://workflowhub.eu/ga4gh/trs/v2"
},
"REGISTRY": {
"base_path": "https://registry.example.org/ga4gh/registry/v1"
}
}
Each base_path is the service's API root, with or without a trailing slash.
The CLI requests service-info and other endpoints below it. Do not include
a query string or fragment. Configs that previously contained only the host
must add the deployed service prefix, such as /ga4gh/tes/v1,
/ga4gh/wes/v1 or /ga4gh/drs/v1 in the example above. A service behind a
gateway keeps its whole prefix, for example
https://gateway.example.org/my-tes/ga4gh/tes/v1.
Profiles¶
The file can hold named profiles for different deployments. Each profile contains the same service sections as the file above:
{
"default_profile": "local",
"profiles": {
"local": {
"TES": {"base_path": "http://localhost:8000/ga4gh/tes/v1"}
},
"remote": {
"TES": {
"base_path": "https://tes.example.org/ga4gh/tes/v1",
"oauth_access_token_env": "REMOTE_TES_TOKEN"
}
}
}
}
Select a profile with --profile, before or after a subcommand, or with
GA4GH_CLI_PROFILE:
The option takes precedence over the variable, and the variable over
default_profile. Without any selection, the CLI uses the profile default.
Files without profiles retain their existing format and count as that
default profile. An unknown or empty profile name is an error; for an
unknown name, the error lists available profiles.
See the usage guide for the file rules.
timeouts sets time limits in seconds for the commands of that section:
connect (default 10), request (default 60), discovery (the service-info
check and the service-info command, default 10) and submission
(tes create and wes run, including uploads, default 300). tes save
applies request to each wait for data of a download instead of to the whole
download. A submission is sent once;
if it runs out of time
after its request started, the error says that it may have been accepted, so look
for the task or run before you submit it again. The
usage guide has the details. Downstream binaries
that call dispatch_with_config() set them with
Configuration::with_timeouts.
Authentication¶
Each built-in service command sends the single configured Basic, OAuth bearer,
or generic bearer credential to its service, including discovery and
submission. workflow submit uses the WES section and the same policy as
wes run. Conflicting sources, unsupported api_key or URL userinfo, and
invalid tokens fail before a request. An _env field can name a variable that
holds the token. Keep the file private (chmod 600 ~/.ga4gh-cli/config.json).
SDK-owned clients do not follow redirects. A section with oidc settings
gets its tokens from the stored login (see
Logging in with OpenID Connect). See the
authentication guide for the source and redirect
contracts, and for the token providers of the Rust and Python APIs.
Logging in with OpenID Connect¶
Instead of pasting a token, you can log in with an OpenID Connect provider
that supports the
device authorization grant (device
flow). Give each section that should use the login an oidc object with the
provider's issuer and a public client ID that the provider has registered for
the device flow:
{
"TES": {
"base_path": "https://tes.example.org/ga4gh/tes/v1",
"oidc": {
"issuer": "https://login.example.org/realms/example",
"client_id": "my-cli-client"
}
}
}
issuer(string, required): the provider's issuer URL. The CLI reads the provider's endpoints from<issuer>/.well-known/openid-configuration. It must use HTTPS; HTTP is accepted only for loopback addresses, such as a local test provider.client_id(string, required): a public client. The CLI sends no client secret, and the configuration can't hold one.scope(string, optional): the scopes to request, separated by spaces. The default isopenid offline_access;offline_accessasks for a refresh token. Some providers need other scopes, for example one that sets the token's audience.
A section with oidc can't also set basic_auth, oauth_access_token,
bearer_access_token or their _env variants. Other keys of oidc are
errors. ga4gh-cli itself has no token variable; to use a token from the
environment for a section, remove oidc and set oauth_access_token_env.
Binaries built on this CLI with a token variable (see the
downstream guide) use the variable's token instead of
the login when the variable is set.
Then log in, naming the section (the service commands' names, such as tes,
stand for their sections):
The CLI shows a URL and a code on standard error. Open the URL in a browser,
enter the code and approve the login. The CLI asks the provider at the
interval the provider sets (by default every 5 seconds, and never more
often than once a second) until you have approved, denied, or the code has expired. It then
stores the tokens in tokens.json next to the configuration file
(~/.ga4gh-cli/tokens.json). It creates the file with mode 0600 and its
directory, if missing, with mode 0700; it refuses to read a file that other
users can access. The CLI never prints the tokens. On Windows, the file gets
the default permissions of its directory. The CLI doesn't use an OS keyring.
Processes that change the store take turns through the lock file
tokens.json.lock next to it. login prints a confirmation, but no token,
on standard error, leaves standard output empty and exits with code 0; it
exits with code 1 if the configuration, the provider, or the approval fails.
Sections with oidc now send the stored access token. When it has expired, or
will within 30 seconds, the CLI refreshes it with the refresh token before the
command and stores the new tokens. If a service rejects the token with 401,
the CLI refreshes it once and sends a read-only request again; submissions are
not resent. If another process has refreshed the tokens in the meantime, the
CLI uses its tokens instead. If the provider issued no refresh token, or
rejects the refresh token (invalid_grant), the command fails and asks you
to log in again; other recognized refresh errors are reported by their OAuth
error code, while unknown codes receive a generic message.
If the CLI can't store refreshed tokens, it still uses them and logs a
warning on standard error. Downstream applications control their own logging.
Tokens are stored per issuer, client ID and scope, so all sections with the
same oidc settings share one login, in every profile. Sections with different
scopes keep separate logins. The token store's directory must be writable.
logout deletes the stored tokens of the section's issuer, client ID and scope and
says so on standard error; it exits with code 0, also if you weren't logged
in. It doesn't revoke the tokens at the provider; they stay valid there until
they expire. Commands that are still running then can't refresh their token
and don't store it again.
--profile selects the profile whose section login and logout read.
Example: Keycloak¶
With Keycloak, the issuer is the realm's URL:
{
"TES": {
"base_path": "https://tes.example.org/ga4gh/tes/v1",
"oidc": {
"issuer": "https://keycloak.example.org/realms/example",
"client_id": "ga4gh-cli"
}
}
}
The client must be public ("Client authentication" off) and have the
"OAuth 2.0 Device Authorization Grant" enabled. For the default scope
openid offline_access, users need the realm role offline_access, which
Keycloak's default roles include. Without it, Keycloak refuses the login
with its own error code not_allowed, which isn't an OAuth error code, so
login reports unrecognized_error. In the browser, Keycloak asks the user
to sign in and then to grant the client access. If the realm rotates refresh
tokens ("Revoke Refresh Token"), each refresh stores the new refresh token;
Keycloak ends the login if an older one is used again, for example from a
copy of the token store, and the CLI then asks you to log in again.
An integration suite checks this setup against a Keycloak container; see the
integration test guide and the test
realm in tests/keycloak/realm.json.
Usage¶
Basic local setup¶
For a local TES server, install Funnel and Docker, then:
-
Install Funnel following the official documentation.
-
Run the Funnel server on port 8000:
- Configure the CLI in
~/.ga4gh-cli/config.jsonusing the example above. Onlybase_pathis needed. Docker must be running for Funnel to execute tasks.
CLI Examples¶
- From the repository root, submit the checked-in
example task. It runs
echoin an Alpine container and has no external inputs or outputs. Save the returned ID for later commands:
The CLI also accepts JSON text directly or from standard input:
ga4gh-cli tes create "$(cat examples/tes-hello.json)"
cat examples/tes-hello.json | ga4gh-cli tes create -
Whatever the source, the CLI sends the task as the JSON it parsed from the
input, including fields that the SDK's TES model doesn't know, at the task
level or nested, for example in an executor. Explicit nulls are kept, and
integers stay integers. Numbers are read as 64-bit integers or as
double-precision floats, so an integer beyond that range or a decimal with
more digits than a double holds is sent rounded. Whitespace and key order may
differ from the input. Whether the service accepts or uses an additional field is up to
the service; it may reject the task. Before contacting the service, the CLI
checks the input: input that isn't valid JSON fails with Failed to parse
JSON, and a task that doesn't match the TES model, such as an executor
without image, fails with Invalid TES task. Both print the reason to
stderr and exit with code 1 without sending a request.
By default the command prints the new task ID as text. For scripts that must
recover an opaque ID exactly, use tes create --format json: it prints
{"id":"..."} with JSON escapes and does not need a subsequent list request.
The shell example above assumes an ordinary ID; command substitution cannot
represent a NUL byte and strips trailing newlines. If the service rejects the
task, the CLI prints the HTTP status to stderr and exits with code 1. It does
not print the server's error body, which may contain echoed credentials.
- To retrieve the list of tasks run
tes listcommand:
Repeat -k and -v to filter by several tags. Values match keys in the
same order. When the response includes a next page token, the CLI prints it
after the task table; pass it to -t to fetch the next page:
To fetch successive pages as one JSON object per line, use:
--max-pages and --max-items limit the export. If the limit stops listing
before the final page, the command exits with code 1 and writes a resume
checkpoint to stderr; already written JSONL stays on stdout.
Example output:
TASK ID State
csei52hrqek3h222k9f0 Complete
csei52hrqek3h222k9eg Initializing
csei52hrqek3h222k9e0 Canceled
csei52hrqek3h222k9dg Running
csei52hrqek3h222k9df Queued
csei52hrqek3h222k9de Queued
- To get task details, run the
tes getcommand:
Possible VIEW values: MINIMAL, BASIC and FULL, in any case. tes list
takes the same values with -w.
The command preserves the server's JSON values and fields unknown to the
current SDK models. Terminal formatting characters inside strings are written
as equivalent JSON escapes.
- To retrieve the task status run the
tes statuscommand:
The command prints the TES state, such as QUEUED, or UNKNOWN for a state
that the TES specification doesn't define (see
Undefined states).
- To cancel a task that is still running, use its ID with
tes cancel:
All five TES commands exit with code 0 on success and code 1 on request or server errors. Missing commands or arguments use Clap's exit code 2. Task IDs, page tokens and error messages are text output, so control characters in them are escaped (see Text and JSON output).
TES logs and output files¶
Three more commands read a task's FULL view and work with its logs and
output files. Nothing is downloaded unless you select it.
- To see what a task has, run
tes files. Each row has a selector for the other two commands:
Example output:
SELECTOR SIZE DESCRIPTION
output:0 - declared output file: s3://bucket/results/out.txt (path /outputs/out.txt)
stdout:0:0 6 executor stdout, 6 bytes, exit code 0
stderr:0:0 0 executor stderr, 0 bytes, exit code 0
system:0 21 system logs, 2 lines
file:0:0 6 output file: s3://bucket/results/out.txt (path /outputs/out.txt)
| Selector | What it names |
|---|---|
stdout:ATTEMPT:EXECUTOR, stderr:ATTEMPT:EXECUTOR |
The stdout or stderr field of an executor log, as text in the response |
system:ATTEMPT |
The system_logs of an attempt, one line per entry |
output:INDEX |
An output that the task declares in outputs |
file:ATTEMPT:INDEX |
An output file that the server reports in the attempt's outputs log, with its size |
Attempts and executors are counted from 0, in the order of the response.
Notes on stderr say what the response lacks, for example when the task is
still running, has no logs yet, or an executor log has no stdout field. URLs
are shown without user names, passwords, query strings and fragments; ?...
marks a removed query string or fragment, which may hold the signature of a
pre-signed URL. tes get "$task_id" FULL shows the complete response.
tes log and tes save print these notes only when they fail.
- To show an inline log, run
tes logwith its selector. Control and bidirectional formatting characters are escaped; line breaks are kept:
- To save logs and output files, run
tes savewith one or more selectors and a directory:
ga4gh-cli tes save "$task_id" stdout:0:0 file:0:0 --dir results
ga4gh-cli tes save "$task_id" output:0 --dir results --name out-copy.txt
The directory is created if it is missing. Inline logs are saved as written
in the response, without escapes, as stdout-0-0.txt, stderr-0-0.txt or
system-0.txt. A file is named after the last part of its path, or of its
URL if the path is empty. --name sets the name instead, for a single
selector. Every file goes into the directory itself: a name with a path
separator, .., or control or bidirectional formatting characters is refused,
whether it comes from the server or from --name, and so is an absolute
--name. An existing file is kept, and the command fails, unless you add
--force, which replaces it.
The command checks all selections and names before it downloads anything. It
then saves the selections in order and stops at the first error; the files
saved before it are listed on stdout. Each download goes to a temporary file in
the directory, which is moved to its name only when the transfer is complete
and, for a file: selector, the number of bytes matches the task's
size_bytes. An HTTP error status, a broken connection, a missing object or a
size mismatch leaves no file behind.
Inline stdout and stderr are whatever the server put in the response: TES
servers may cut them short or leave them out. To keep complete output, have
the executor write it to a file (with the executor's stdout and stderr
paths) and declare that file in outputs, then save it as a file: or
output: selection.
Supported URL schemes:
httpandhttps: The CLI sends a plainGETrequest and follows redirects. It sends no credentials from the configuration file, since output URLs can point to any host. Use URLs that need no credentials, such as pre-signed URLs. Proxy environment variables apply.s3:s3://BUCKET/KEY. Region and endpoint come from standard AWS environment variables. Credentials can come fromAWS_*variables or, when no static keys are set, from the credential providers used byobject_store, including cloud instance metadata. A selected S3 URL may therefore use the machine's instance role. Relevant variables includeAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,AWS_REGION(defaultus-east-1) andAWS_ENDPOINT(for S3-compatible storage such as MinIO; addAWS_ALLOW_HTTP=truefor a plain HTTP endpoint). SetAWS_SKIP_SIGNATURE=truefor public buckets. Requests that fail temporarily are retried up to three times.
Both use the connect time of the TES section for a connection. The
request time (default 60 seconds) bounds the wait for the storage response
and each later wait for body data; a download as a whole has no time limit.
Saved files get the permissions that the umask allows, as with other new files.
Debug logs of the HTTP libraries
show full URLs, so the CLI logs them only when RUST_LOG names them, for
example RUST_LOG=debug,reqwest=debug.
Other schemes, such as file, gs or ftp, are refused with an error, and
so are declared outputs of type DIRECTORY or with a wildcard: save the files
that the server reports under file: instead. A declared output counts as a
wildcard when its path contains *, ? or [, or when it has a non-empty
path_prefix; an empty path_prefix, which some servers send for single
files, leaves a FILE output a file.
The three commands exit with code 0 on success and code 1 on request, server,
selection or download errors; missing arguments, such as --dir, use exit
code 2. Invalid selectors and --name values fail before the CLI contacts
the service.
DRS examples¶
Add a DRS section with the service's API root to the configuration file, as
shown above. Use drs get to read object metadata, then use an access_id from
its access_methods to request a URL for the object's bytes:
Both commands preserve the server's JSON values. The access result may
contain headers needed to fetch the bytes. Service failures print an error to
stderr, escaped as described in Text and JSON output,
and exit with code 1; missing arguments use exit code 2.
WES examples¶
Add a WES section with the service's API root to the configuration file, as
shown above. The commands follow the TES commands: submit a run, then track it
by its ID.
- To submit a workflow, run
wes runwith the workflow URL, the workflow type and the version of the type. Parameters are optional (an empty object by default) and, as withtes create, can be a JSON file, inline JSON or-for standard input. By default the command prints the new run ID as text:
run_id=$(ga4gh-cli wes run 'https://example.org/workflows/main.cwl' \
--type CWL --type_version v1.2 --params params.json)
printf '%s\n' "$run_id"
For an exact machine-readable ID, use wes run --format json. Its output is
{"run_id":"..."} with JSON escapes. The shell example assumes an ordinary
ID; command substitution cannot represent a NUL byte and strips trailing
newlines.
Repeat --attachment (-a) to upload workflow files with the request. Each
file is uploaded under the relative path given, so run the command from the
directory that the paths are relative to; absolute paths and .. are
rejected. Symbolic links are followed, so check the files of a repository
that you don't trust before you attach them. WORKFLOW_URL can then name an
attached file, if the service supports attachments:
ga4gh-cli wes run main.cwl --type CWL --type_version v1.2 \
-a main.cwl -a tools/step.cwl --params '{"reads": "a.fastq"}'
--tag KEY=VALUE and --engine_parameter KEY=VALUE can be repeated;
--engine and --engine_version select a workflow engine if the service
offers several. Input errors, such as invalid JSON or a missing attachment, are
reported before the CLI contacts the service.
- To list runs, run
wes list:
Example output:
RUN ID STATE
3f2a0b6e-58c2-4e8a-9d1e-0c5b7a1d2e3f RUNNING
9c1d4e2a-7b3f-4a6e-8d5c-1e2f3a4b5c6d COMPLETE
Next page token: next
As with tes list, -p sets the page size, -t passes the next page token,
and --all --format jsonl writes every run as one JSON object per line, with
the same --max-pages and --max-items limits.
- To get the details of a run, including its request, logs and outputs, run
wes get. It preserves the server's JSON values, escaping terminal formatting characters inside strings:
- To get the state of a run, such as
RUNNINGorCOMPLETE, runwes status. A state that the WES specification doesn't define is printed asUNKNOWN(see Undefined states):
- To cancel a run, run
wes cancel. It prints the ID of the canceled run:
All five WES commands exit with code 0 on success and code 1 on request or
server errors; missing commands or arguments use exit code 2. In the table,
the printed run IDs and the error messages, control and bidirectional
formatting characters from the server are escaped, such as \u{1b}; JSONL
records use JSON escapes such as \u001b. Like tes get and drs get,
wes get preserves the server's JSON values and unknown fields.
TRS examples¶
The trs commands browse a GA4GH Tool Registry Service (TRS), such as
WorkflowHub or Dockstore, and download workflow files from it. They only read
from the registry; nothing is changed there.
The CLI uses the SDK's TRS compatibility policy.
--api-version auto (default) recognizes 2.0.1 and 2.0.2. An unknown declaration
uses the 2.0.1 read contract without assuming tag-filter support.
--api-version strict requires a recognized declaration;
--api-version 2.0.1 or 2.0.2 selects an API profile explicitly.
These flags can appear before or after a TRS subcommand.
--tag-filter enabled allows a known deployment's backported tag filter;
--tag-filter disabled blocks filtering on a deployment that does not implement
it. Neither option changes the response contract. Use overrides only with
independent knowledge of the server, not just because it returned HTTP 200.
For a known endpoint without usable service-info, combine --no-discovery
with an explicit version. Discovery failures never trigger this automatically.
# Require a recognized server declaration.
ga4gh-cli trs --api-version strict tools --limit 1
# Use a known 2.0.1 deployment's backported tag filter.
ga4gh-cli trs --api-version 2.0.1 --tag-filter enabled tools --tag genomics
# Read a known endpoint that does not expose service-info.
ga4gh-cli trs --no-discovery --api-version 2.0.1 tools --limit 1
1. Configure the registry¶
The trs commands need to know which registry to talk to. They read it from
the TRS section of the CLI's configuration file, ~/.ga4gh-cli/config.json
(see Configuration). The CLI uses one registry at a time.
a. Choose a registry. Its base_path is the registry's TRS API root.
| Registry | base_path |
Tool IDs look like |
|---|---|---|
| WorkflowHub | https://workflowhub.eu/ga4gh/trs/v2 |
26 |
| Dockstore | https://dockstore.org/api/ga4gh/trs/v2 |
#workflow/github.com/org/repo |
b. Add the TRS section to the configuration file. For a file containing
only TRS configuration, the full JSON is:
c. Check the connection. This lists one tool from the registry:
2. Find a tool, pick a version, download its files¶
A registry holds tools. Each tool has versions, and each version has
one or more descriptors: workflow files written in a language such as CWL
or WDL. Replace TOOL_ID and VERSION_ID below with values returned by the
registry:
# Find tools. All filters are optional; repeat --tag for several tags.
ga4gh-cli trs tools --tool-class Workflow --descriptor-type CWL --limit 5
# Look at one tool and its versions.
ga4gh-cli trs tool 'TOOL_ID'
ga4gh-cli trs versions 'TOOL_ID'
ga4gh-cli trs version 'TOOL_ID' 'VERSION_ID'
# See which files the version has, then download the main workflow file.
ga4gh-cli trs files 'TOOL_ID' 'VERSION_ID' --type CWL
ga4gh-cli trs descriptor 'TOOL_ID' 'VERSION_ID' --type CWL --plain > main.cwl
# Or download all files of the version as one ZIP archive.
ga4gh-cli trs files 'TOOL_ID' 'VERSION_ID' --type CWL --zip workflow.zip
Commands¶
| Command | Result |
|---|---|
trs tools [filters] |
A list of tools, optionally filtered by --tool-class, --descriptor-type, --organization, --name and --tag (repeatable), paged with --offset and --limit. |
trs tool <TOOL_ID> |
One tool and its versions. |
trs versions <TOOL_ID> |
The versions of a tool. |
trs version <TOOL_ID> <VERSION_ID> |
One version, its descriptor types and, if the registry sends one, its description. |
trs files <TOOL_ID> <VERSION_ID> --type <TYPE> |
The paths and types of its files; --zip <FILE> writes all files as one ZIP archive to FILE instead. |
trs descriptor <TOOL_ID> <VERSION_ID> --type <TYPE> |
Its primary descriptor; --path <RELATIVE_PATH> selects another file. |
trs tests <TOOL_ID> <VERSION_ID> --type <TYPE> |
Its test parameter files. |
Results are JSON by default. trs descriptor --plain prints the descriptor
content without a JSON wrapper. trs tests --plain prints one inline test file;
if the server returns several files or only a URL, omit --plain to inspect
their JSON instead. The commands exit with code 0 on success and 1 on request
or server errors; missing arguments use exit code 2. --zip never replaces
an existing file, doesn't extract the archive, and downloads at most 64 MiB;
the file appears under its name only when it is complete (until then, it is a
hidden .<name>.partial-<pid> file in the same directory, which an interrupted
download may leave behind, so the name may be up to about 18 bytes shorter than
the filesystem allows). On filesystems without hard links, such as FAT, the
archive is written to the file directly.
A tag must not be empty or contain a comma, because the registry receives all
tags as one comma-separated value. Error messages and JSON
output escape terminal control and bidirectional formatting characters.
Service Registry commands¶
The registry commands read a GA4GH Service Registry,
such as a cloud-registry
deployment, to find the base URLs of TES, WES and other services. They use the
REGISTRY section of ~/.ga4gh-cli/config.json, which needs only base_path,
the registry's API root:
Replace registry.example.org with your registry's host.
The CLI requests services, services/{id} and services/types below this
path. Public reads need no token; a deployment that requires authentication
can use one of the configured sources in the
authentication guide.
- To list the services, optionally only those of one type artifact (case
ignored), run
registry list:
Example output:
- To get one service as JSON, run
registry getwith its ID:
- To list the service types in the registry, one
group:artifact:versionper line, runregistry types:
The specification has no server-side filter, so --type fetches all services
and filters them in the CLI.
list and types print only fields of the Service Registry specification;
get also prints the fields that a registry adds. Control and bidirectional
formatting characters from the registry, in values and in error messages, are
printed escaped, such as \n or \u{1b}; get uses JSON escapes such as \u001b,
so its output stays valid JSON. The commands exit with code 0 on
success and code 1 on request or server errors. A 404 from list or types
adds a hint to check base_path; from get, a 404 means that no service has
that ID.
Service Info command¶
service-info prints the service info
of one configured service. It can include an ID, name, type, organization,
version and provider-specific fields. --service names the section of the
configuration file to read, such as TES, WES, DRS, TRS, REGISTRY or a
custom section; names are case sensitive. --profile selects the profile as
for the other commands:
The command requests service-info below the section's base_path, with or
without a trailing slash, using the section's credentials (see
Authentication) and its discovery timeout (see
Profiles). It needs no other setting, so a custom section with only
base_path works:
Example output, as the service sent it:
{"id":"org.example.tes","name":"Example TES","type":{"group":"org.ga4gh","artifact":"tes","version":"1.1.0"},"organization":{"name":"Example","url":"https://example.org"},"version":"1.0.0","storage":["s3://bucket"]}
On success, stdout holds the response body and nothing else, like tes get:
the server's values, field order, whitespace and number spelling are kept,
including the fields that the service adds at the top level and in type and
organization. Control and bidirectional formatting characters inside strings
are printed as JSON escapes such as \u001b, so the output stays valid JSON
with the same values. Pipe it through a JSON tool, such as jq ., to indent it.
The body must be a JSON object. The command prints its fields without checking
them against the generic ServiceInfo::get() model. This also works with the
native WES 1.0 service-info shape, which omits some generic fields. The typed
Rust and Python ServiceInfo clients still apply their documented model
contract; use them when you need those fields checked. The CLI's output alone
does not certify that a service conforms to a particular schema.
The command exits with code 0 on success and code 1 on errors, with one message on stderr and nothing on stdout:
- a missing configuration file, profile or section, or a missing login or token variable, is reported before any request is sent;
- an HTTP error status is reported with the status but without the response
body; a 404 adds a hint to check that
base_pathis the section's API root; - malformed JSON or a JSON value that is not an object is reported as
Invalid service info from section '<SECTION>'; - a connection failure or an exceeded
discoverytimeout is reported by category, without exposing the URL or lower-level source text.
Credentials are never printed. A missing or empty --service is a usage error
with exit code 2.
Experimental workflow contracts¶
wes operates the WES service API: submit a run and inspect its state and
outputs. workflow provides client-side contracts around a run: validate a
pinned request, submit it explicitly through WES, project and verify selected
results, and compare runs against a policy. It is not a second workflow
execution service. See the workflow contracts guide
for the commands and their evidence boundaries.
Text and JSON output¶
All commands treat values from a service the same way:
- Text output, such as tables, bare task and run IDs, page tokens, and error
and log messages on stderr, shows control and bidirectional formatting characters as
Rust escapes, such as
\n,\u{1b}or\u{202e}. Other characters, including backslashes, are printed as they are, so an escaped value can't be told apart from a value that contains the same backslash sequence. Values without such characters are printed unchanged. tes get,wes get,drs get,drs accessandservice-infopreserve the server's JSON values, field order, whitespace and number spelling. Raw control and bidirectional formatting characters inside strings become equivalent JSON\uescapes. A response that isn't valid JSON is reported as an error on stderr, with exit code 1. JSON may still contain layout whitespace between values; its strings cannot contain unescaped C0 controls such as ESC.tes list --all --format jsonlandwes list --all --format jsonlwrite each record with JSON escapes, such as\u001b, which decode to the original value.registry getand the JSON output of thetrscommands use JSON escapes in the same way.trs descriptor --plainandtrs tests --plainprint the file content as received, since it is meant to be saved as a file.tes logescapes each line of a log like other text output and keeps the line breaks.tes savewrites logs and files as received, without escapes.
Escaping changes only what is printed. The SDK keeps the values it received,
and commands send the IDs given to them unchanged. For a newly submitted ID,
use tes create --format json or wes run --format json and parse the id
or run_id field in the calling program. For an ID shown in a table, the
JSONL exports retain its original value: tes list --all --format jsonl and
wes list --all --format jsonl.
Undefined states¶
A server may report a task or run state that its specification doesn't
define, such as SUSPENDED. The commands that read the state into the SDK
models show such a state as the specification's UNKNOWN: tes status,
wes status and the wes list table print UNKNOWN, and the tes list
table prints Unknown. The wes list table also shows a run without a state
as UNKNOWN, while the tes list table shows None. tes get and wes get
show the server's value as it is, and so do the JSONL exports of
tes list --all and wes list --all. Use one of those to see which state the
server actually reported.
Extending the CLI in Rust¶
The ga4gh-cli package also exposes a Rust library. A downstream binary can
add its own Clap 4 subcommands to ga4gh_cli::command(). Call
ga4gh_cli::dispatch() for the built-in commands, or
ga4gh_cli::dispatch_with_config() to supply a service configuration directly.
Both return None when the downstream binary should handle its own command.
Built-in commands return stdout, stderr, and an exit code in CommandOutput,
so the downstream binary can write or reformat their output; stderr and the
text parts of stdout are already escaped as described above.
ga4gh_cli::printable() escapes a value in the same way for a downstream
binary's own text output. SDK log messages can hold a service's response, so
a downstream binary that writes logs should pass them through printable()
too, as the ga4gh-cli binary does in its logger setup. See the
downstream CLI test for a working example. A
downstream command that shares the ga4gh-cli file can read its own section
with Configuration::from_file(ServiceType::Custom("MY_SERVICE".into()));
keys that the SDK doesn't use itself are in Configuration::extra.
dispatch() runs service-info with the section that --service names, also
a downstream binary's own section; dispatch_with_config() uses the supplied
configuration, and --service then only names the section in error messages.
A downstream binary with its own name, version, configuration file, profile
variable or token variable describes them in a ga4gh_cli::CliContext:
CliContext::new("my-cli", env!("CARGO_PKG_VERSION"))sets the name and version;with_about()sets the help text.- The configuration file defaults to
~/.my-cli/config.json. The name must then be usable as a directory name;with_config_path()sets another path.load_config()reads a section from the file, for built-in and custom services alike. with_profile_env("MY_CLI_PROFILE")reads a selected profile from a variable.ga4gh-clireadsGA4GH_CLI_PROFILE; other contexts read none unless configured.with_profile()selects one directly. The command tree has a global--profileoption, whichdispatch()anddispatch_to()apply. For a custom command, callwith_profile_from(&matches)beforeload_config(). The long option name--profileis reserved in the tree.with_token_env("MY_CLI_TOKEN", [ServiceType::Custom("MY_SERVICE".into())])supplies an OAuth access token to the listed sections when they set no credentials. Other sections never receive it. If a listed section has no credential, the variable must be present and contain a valid token; otherwise the command fails before sending a request.- Its
command(),dispatch()anddispatch_to()replace the free functions, which keep the settings ofga4gh-cli.dispatch_with_config()anddispatch_with_config_to()take a configuration from the caller and don't need a context. - Its own commands can build their output as the built-in ones do:
CommandOutput::json()andfailure()escape their content and set the exit code,success()takes text that is already escaped, andwrite_to()writes both streams and returns the exit code.
The guide Build on this SDK walks through an example crate.