BaseSpace Sequence Hub (BSSH) is the Illumina cloud-based platform for data management, storage, and analysis. Illumina sequencing instruments can be configured to upload run data to BaseSpace Sequence Hub if designated at the time of run setup. Now, using the BaseSpace Command Line Interface (CLI) tool, instrument run data can be uploaded to BaseSpace Sequence Hub after a run is complete. This bulletin provides details for how to use the run upload function of BaseSpace CLI. A short video tutorial on how to upload runs using BaseSpace Command Line Interface (CLI) can be accessed on the Illumina Support Shorts YouTube playlist.

Note:

• The run upload function requires at least version 1.2.0 of BaseSpace CLI. To check the version that you have installed, run the command: bs --version
• BaseSpace CLI requires familiarity with operating in a command-line environment.

Installation notes:

• BaseSpace CLI is available for Linux, Mac OS X, and Windows.
• The BaseSpace CLI page contains download and authentication instructions.
• If your system does not have the wget download tool installed, the bs executable can be manually downloaded following the links for the appropriate platform, Linux, Mac, or Windows.

Add CREATE RUNS scope to config

Uploading a run folder to BaseSpace Sequence Hub with BaseSpace CLI requires the authentication scope CREATE RUNS.

If you have used BaseSpace CLI previously, you can confirm your current scopes by using the command: bs whoami

The account in the example below does not contain the CREATE RUNS scope:

To add the CREATE RUNS scope, copy the list of current scopes and add CREATE RUNS to the list, and reauthenticate with the --force option.

Note:  displaying the scopes in CSV format with bs whoami -f csv can make the values easier to copy.

Using the scopes shown in the list above, an example command is:

bs authenticate --scopes "READ GLOBAL, CREATE GLOBAL, BROWSE GLOBAL, CREATE PROJECTS, START APPLICATIONS, MOVETOTRASH GLOBAL, WRITE GLOBAL, CREATE RUNS" --force

Important Notes:

• The list of scopes must be contained in quotation marks and contain the full list of scopes. Authenticating with only the CREATE RUNS scope removes the rest of the previously existing scopes.
• This example adjusts the scopes for your default configuration. Other configs set to authenticate to workgroups or other domains can also be similarly edited.

After reauthentication, confirm that CREATE RUNS is in your list of scopes by again using the bs whoami command. The example account below contains CREATE RUNS along with the rest of the previous scopes:

New users: add CREATE RUNS scope to config

If you are using BaseSpace CLI for the first time, authenticate without the --force option, and include the CREATE RUNS scope along with the desired scopes. This example contains CREATE RUNS along with the default scopes:

bs authenticate --scopes "READ GLOBAL, CREATE GLOBAL, BROWSE GLOBAL, CREATE PROJECTS, START APPLICATIONS, MOVETOTRASH GLOBAL, WRITE GLOBAL, CREATE RUNS"

Uploading a run with CLI

When uploading a run folder to BaseSpace Sequence Hub, the folder must contain the standard Illumina run files, such as the Data folder, RunInfo.xml, and RunParameters.xml. A sample sheet file, named as SampleSheet.csv, is required to start FASTQ Generation automatically after the run upload is complete.

The command to upload a run folder with BaseSpace CLI is upload run, and requires a run name, instrument type information, and a path to the local run folder, in the format of:
bs upload run -n {RunName} -t {InstrumentType} {PathToRunFolder}

Run name (-n) values should contain only alphanumerics, and no spaces or special characters.

Valid options for the instrument type (-t) flag include:

• HiSeq family: HiSeq1000, HiSeq1500, HiSeq2000, HiSeq2500, HiSeq3000, HiSeq4000, HiSeqX
• NovaSeq family: NovaSeq5000, NovaSeq6000
• Other instruments: MiniSeq, MiSeq, MiSeqDx, NextSeq, NextSeqDx, NextSeq2000, iSeq100

An example complete valid upload command is:
bs upload run -n UploadedRun -t MiSeq /runs/MyRunFolder

File Exclusions

By default, the upload run command uploads all contents of the run folder. To save space in your BaseSpace account or decrease upload time, certain files and folders can be excluded from the upload.

• Unwanted file types in the run folder, such as .jpgs from thumbnails, can be excluded from the upload with the --skip-ext= option, such as:
  --skip-ext=jpg
• Unwanted folders, such as an Alignment folder from a local analysis, can be excluded with the --skip-dir= option, such as:
  --skip-dir=Alignment_1

Further information and upload options are available on the BaseSpace CLI Examples page.