Using the BaseSpace Command Line Interface (CLI) Tool on the NovaSeq X Series

Background

The BaseSpace CLI tool allows a user to upload run data to BaseSpace for monitoring run metrics or performing data analysis in the cloud. As the NovaSeq X Series instruments splits certain run data across two different locations, this requires the use of specific command line options to ensure the data is uploaded correctly.

Installing and Authorizing the CLI Tool

1. Login to the instrument using the ilmnadmin Linux Operating System (OS) account.

   1. If currently logged in as ilmnuser, exit the Control Software and log out of the ilmnuser account, then log into the Linux OS using the ilmnadmin account.

2. Open Chromium and navigate to the BaseSpace CLI Overview page, then download the Linux CLI Tool to the /home/ilmnadmin/Downloads directory on the instrument.

3. From the Linux OS, select the Activities menu in the top-left corner, then open the Terminal app.

4. Input the command cd ~/Downloads and press Enter to navigate to the Downloads directory.

5. Input the command chmod 775 bs and press Enter to enable script execution permissions for the CLI script.

6. Input the command ./bs auth to generate an authorization link.

7. Hold the Ctrl button and then click the link to open the link in Chromium, then input your BaseSpace login credentials.

8. On successful authentication, the Terminal will show a successful login message.

General CLI Syntax

The CLI Tool will use the following syntax for identifying the location of files to send to BaseSpace. Different options can be used to specify separate locations for the RunParameters.xml and SampleSheet.csv files, as well as directories to omit depending on the user needs.

For each command, the [ ] are placeholders and should be omitted from the final command after inputting the RunName, InstrumentType, and RunID information.

./bs upload run -n [RunName] -t [InstrumentType] [OPTIONS] /usr/local/illumina/mnt/runs/[RunID]

• upload run Calls the 'upload run' module within the CLI Tool

• -n [RunName] Provides BaseSpace with a name for the sequencing run.

• -t [InstrumentType] Provides BaseSpace with the instrument type, either NovaSeqX or NovaSeqXPlus.

• [OPTIONS] Provides the CLI Tool with options including location of the RunParameters.xml or SampleSheet.csv files, as well as directories and files to skip if they are not needed.

• /usr/local/illumina/mnt/runs/[RunID] Provides the CLI Tool with the location of the run data on the instrument.

Uploading Run Metrics Files Only (Cloud Run Monitoring)

This command will trigger upload of the run metrics files only and is similar to the Cloud Run Monitoring option. The general syntax for the command is as follows:

./bs upload run -n [RunName] -t [InstrumentType] --run-parameters=/usr/local/illumina/runs/[RunID]/RunParameters.xml --skip-dir=Data/ --skip-dir=Thumbnail_Images/ --exclude='*.out' /usr/local/illumina/mnt/runs/[RunID]

• --run-parameters=/usr/local/illumina/runs/[RunID]/RunParameters.xml Provides the CLI Tool with the specific location of the RunParameters.xml file.

• --skip-dir=Data/ --skip-dir=Thumbnail_Images/ Forces the CLI Tool to skip the Data/ and Thumbnail_Images/ directories as these are not needed for Cloud Run Monitoring.

• --exclude='*.out' Indicates to the CLI Tool to skip certain log files that are not required for upload to BaseSpace.

Uploading Run Metrics and Data Files for Analysis (Cloud Run Storage)

This command will trigger upload of both run metrics and run data files to BaseSpace and is similar to the Cloud Run Storage option. This method will be required if the user intends to use Cloud Apps such as such as BCL Convert or other DRAGEN Apps to process the data in the Cloud.

If a SampleSheet.csv file is available, it can be uploaded and will automatically trigger analysis with the configured Apps listed in the SampleSheet.csv file. If a SampleSheet.csv file is not available at the time of upload, this option can be omitted from the command entry.

./bs upload run -n [RunName] -t [InstrumentType] --run-parameters=/usr/local/illumina/runs/[RunID]/RunParameters.xml --samplesheet=/usr/local/illumina/runs/[RunID]/SampleSheet.csv --skip-dir=Thumbnail_Images/ --exclude='*.out' /usr/local/illumina/mnt/runs/[RunID]

• --run-parameters=/usr/local/illumina/runs/[RunID]/RunParameters.xml Provides the CLI Tool with the specific location of the RunParameters.xml file.

• --samplesheet=/usr/local/illumina/runs/[RunID]/SampleSheet.csv Provides the CLI Tool with the specific location of the SampleSheet.csv file.

• --skip-dir=Thumbnail_Images/ Forces the CLI Tool to skip the Thumbnail_Images/ directory as this are not needed for Cloud Storage.

• --exclude='*.out' Indicates to the CLI Tool to skip certain log files that are not required for upload to BaseSpace.

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