Command-Line Interface

TruSight Software includes a command-line interface (CLI) that supports uploading and downloading FASTQ files and analysis output.

• The CLI tool requires JVM 11 and is intended to run on Linux CentOS.
• The user associated with the API key must be a domain administrator and a member of the workgroup to which the files are uploaded. For information about generating API keys, see Generating an API Token.

This section provides instructions for generating a new API token. All CLI operations require a token for authentication.

1. Select Manage API Keys from the Account drop-down list.
2. Select Generate.
3. Enter a name for the API key.
4. To generate a global API key, select All workgroups and roles.

You can edit the generated key to change this selection.

5. Select Generate.
6. From the API Key Generated dialog, select an option.
• Show—Reveals the API key.
• Download API Key—Downloads the API key in TXT file format.

You will not be able to view the API key again after closing this dialog. The API key cannot be recovered, but you can regenerate the key or create new API keys at any time.

7. Select Close after you have stored the API key.

The API key is added to the Manage API keys list.

8. Perform any of the following actions in the Manage API Keys list.
• Select Regenerate to generate a new API key with the existing API key name.
• Select the Edit icon to edit the API key name or change the workgroups and roles selection.
• Select the Delete icon to permanently delete the API key.
1. Select Download CLI Tool from the Account drop-down list.
2. [Optional] Create an alias for the CLI.

bash alias tss='java -jar tss-cli-<version>.jar'

The examples in this section use the alias tss.

3. Configure the tool using the configure command.

tss configure --domain <domain> --workgroup <workgroupid> --url <url> --apiKey <apiKey>

Flag

Description

--domain

The user domain.

--workgroup

The workgroup ID.

To find the workgroup ID, open the Admin Console and select a workgroup. The ID appears as an alphanumeric string in the URL for the selected workgroup.

--url

The host URL, excluding http (eg, name.trusight.illumina.com). For accounts on a specific domain the name is cac1, euc1, euw2, etc. (eg, cac1.trusight.illumina.com).

--apiKey

Your API key.

If the key contains non-alphanumeric characters, enclose the string in single quotes '.

--configFile

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

The command creates a configuration file with the specified parameters. Unless specified by --config-file, the file is saved to the default path ~/.illumina/uploader-config.json.

The API key can optionally be written directly to the uploader-config.json file after configuration.

Example:

tss configure --domain ilmn-demo--workgroup $12345-45667-234234 --url name.trusight.illumina.com --apiKey 'zX9lY(ZtCZDoKht0ag2'

4. Copy the URL into your browser, and then log on to your account.

Manage samples using the commands listed in the following table.

Commands

Description

create

Create a sample.

delete

Delete a sample and all files referenced by the sample.

get

Get details about a sample.

list

Get list of samples.

Create

Usage:

tss samples create [--overwrite] [--configFile=<configFile>] --manifest=<arg1> --sampleId=<arg0>

Flags

Description

--manifest

Path to the manifest file. See Sample Manifest JSON.

Store the manifest file in the same directory as the samples.

--overwrite

[Optional] Overwrite a sample. Apply this flag to modify FASTQ files for the sample.

This flag only applies to an existing sample. To determine if the sample exists, use samples get or samples list.

--sampleId

Unique ID for the sample. 100 characters maximum. (0-9, a-z, upper case / lower case, _, -)

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

Delete

You can delete sample files that are stored in TruSight Software. Sample files streamed from instruments are stored in BaseSpace Sequence Hub and cannot be deleted by TruSight Software. Use BaseSpace Sequence Hub to delete sample files from instruments.

Samples cannot be deleted if they are referenced by at least one case with a status other than In Progress - Awaiting Molecular Data.

Deleting a sample also deletes any files referenced by the sample. If multiple samples reference a file, deleting one of the samples can break the remaining samples.

Usage:

tss samples delete [--configFile=<configFile>] --sampleId=<arg0>

Flags

Description

--sampleId

Unique ID for the sample.

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

Get

Usage:

tss get [--configFile=<configFile>] --sampleId=<arg0>]

Flags

Description

--sampleId

Unique ID for the sample.

List

Usage:

tss samples list [--configFile=<configFile>][--idPrefix=<arg0>] [--orderBy=<arg1>] [--pageNumber=<arg4>] [--pageSize=<arg3>] [--sortOrder=<arg2>]

Flags

Description

--idPrefix

Sample ID prefix.

--orderBy

Field by which to sort the response.

--pageNumber

The results page to retrieve (0-indexed)

--pageSize

Number of results to return per page.

--sortOrder

Sort order, ASC or DESC.

Manage analyses using the commands listed in the following table.

Commands

Description

create

Create an analysis.

delete

Delete an analysis.

get

Get details about an analysis.

list

Get list of analyses.

Create

Usage:

tss analyses create [--overwrite] [--verbose][--configFile=<configFile>] --manifest=<arg1> --analysisId=<arg0> --regex=<arg3>

Flags

Description

--analysisId

Unique ID for the analysis.

--manifest

Path to the manifest file. See Analysis Manifest JSON.

--overwrite

Overwrite an existing analysis.

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

--regex

[Optional] Regular expression to filter files by file path.

Delete

Usage:

tss analyses delete [--configFile=<configFile>] --analysisId=<arg0>

Flags

Description

--analysisId

Unique ID for the analysis.

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

Get

Usage:

tss analyses get [--configFile=<configFile>] --analysisId=<arg0>]

Flags

Description

--analysisId

Unique ID for the analysis.

List

Usage:

tss analyses list [--configFile=<configFile>][--idPrefix=<arg0>] [--orderBy=<arg1>] [--pageNumber=<arg4>] [--pageSize=<arg3>] [--sortOrder=<arg2>]

Flags

Description

--idPrefix

Analysis ID prefix.

--orderBy

Field by which to sort the response.

--pageNumber

The results page to retrieve (0-indexed)

--pageSize

Number of results to return per page.

--sortOrder

Sort order, ASC or DESC.

Manage files using the commands listed in the following table.

Commands

Description

download

List or download files. By default, files are downloaded to the current working directory.

list

Get list of remote files.

Download

TruSight Software uses the following path to store uploaded files: gds://<volumeName>/<workgroup>/cases/<caseIdGuid>. For more information, see Analysis Data.

Usage:

tss files download [--matchPathExactly] [--configFile=<configFile>] --path=<arg0> --targetDir=<arg1>

Flags

Description

--analysisId

Unique ID for the analysis.

--path

Remote path to file or directory.

--targetDir

The local folder into which to download the files.

--config-file

[Optional] Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json

--matchPathExactly

[Optional] If set, only the file that matches the path exactly is returned.

List

Usage:

tss files list [--includePresignedUrl] [--matchPathExactly] [--configFile=<configFile>] --path=<arg0>

Flags

Description

--includePresignedUrl

[Optional] If set, the response include presigned URLs for each file.

--matchPathExactly

[Optional] If set, only the file that matches the path exactly is returned.

--path

Remote path to file or directory.

The TruSight Software CLI supports the following global flags for all commands.

Global Flag

Description

-h

--help

Help for completion.

--config-file

Path to the uploader configuration file. The default path is ~/.illumina/uploader-config.json.

--threads

The number of threads to use for upload or download.

-V

--version

CLI version.

--verbose

Turn on INFO logging.