How to use the TruSight Software Suite (TSS) CLI uploader

TruSight Software Suite (TSS) relies on a command line tool (similar to BaseSpace CLI) to upload FASTQ files into the system. The latest version of the CLI tool can always be downloaded directly from within TSS.

Download and Verify CLI Uploader

There are prerequisites that are necessary before installing and running the TSS CLI uploader, outlined below.

• 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.

Downloading the CLI Uploader

1. Download the tss-cli-.zip from TSS (see above). Unzip this folder to get the tss-cli-.jar file.

2. Confirm the expected output is seen from the command below to verify the tool is functional on the system.

$ java -jar tss-cli-<version>.jar -h``Usage: tss-cli.jar [-hV] [--verbose] [--configFile=<configFile>] [--threads=<numThreads>] [COMMAND] TSS Command-line Interface (CLI) for analysis, sample, and file operations --configFile, --config-file=<configFile> Path to the uploader configuration file. Defaults to ~/.illumina/uploader-config.json -h, --help Show this help message and exit. --threads=<numThreads> Number of threads to use for upload and download -V, --version Print version information and exit. --verbose Turn on INFO logging Commands: help Displays help information about the specified command configure Configure wgs-cli tool analyses, analysis create, list, get, and delete analyses samples, sample create, list, get, and delete samples files List or download files

Configure and Authenticate CLI Uploader

1. Retrieve the domain for the account; this is the text that precedes .trusight.illumina.com in the URL when on the TSS Dashboard: https://<domain>.trusight.illumina.com/cmp/cases/dashboard

2. Retrieve the W****orkgroupID for the workgroup that data will be uploaded to, from the Illumina Identity and Access Management (IAM) console.

   1. Navigate to IAM from the dropdown menu in the upper right of the TSS screen.

   2. When in IAM, select the desired workgroup from those available in the list.

   3. When the workgroup configuration page loads, the workgroupID will be found in the URL: https://.login.illumina.com/iam/#/workgroup/edit/<workgroupID>/overview

3. The url that will be used is trusight.illumina.com.

4. The apiKey can be obtained from the console. For further information about generating an API Token, please search for Knowledge Base article Trusight Software Suite (TSS) How to generate API keys for TSS.

5. Configure the uploader tool using the configure command:

$ java -jar tss-cli-<version>.jar -h Usage: tss-cli.jar [-hV] [--verbose] [--configFile=<configFile>] [--threads=<numThreads>] [COMMAND] TSS Command-line Interface (CLI) for analysis, sample, and file operations --configFile, --config-file=<configFile> Path to the uploader configuration file. Defaults to ~/.illumina/uploader-config.json -h, --help Show this help message and exit. --threads=<numThreads> Number of threads to use for upload and download -V, --version Print version information and exit. --verbose Turn on INFO logging Commands: help Displays help information about the specified command configure Configure wgs-cli tool analyses, analysis create, list, get, and delete analyses samples, sample create, list, get, and delete samples files List or download files

1. A file called uploader-config.json will be created in a hidden folder within the user's home folder (~/.illumina/) which will have the domain, workgroup, url and apiKey saved within it.

2. Verify these details are correct by viewing the file contents.

$ cat ~/.illumina``/uploader-config``.json``{``"domain"``:``"ilmn-demo"``,``"workgroup"``:``"<workgroupID>"``,``"url"``:``"trusight.illumina.com"``,``"apiKey"``:"<apiKey>"}

Upload FastQ files

FastQ files must be associated with samples while being uploaded to TSS. This can be done by providing a sample manifest while during the upload command. An example Sample Manifest JSON can be found here.

1. Upload FASTQ files using the following command: $ java -jar tss-cli-.jar samples create --manifest /local/path/to/manifest.json --sampleId

Below are other flags that can be used with this command.

java -jar tss-cli-<version>.jar configure --domain <domain> --workgroup <workgroupID> --url <url> --apiKey <apiKey>

More information about using TSS CLI is available here.

For any feedback or questions regarding this article (Illumina Knowledge Article #3407), contact Illumina Technical Support [e-mail].