How to upload a run to BaseSpace using BaseSpace Command Line Interface (CLI)

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. Notes:

• 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

• As of version 1.2.1 of BaseSpace CLI the CREATE RUNS scope is added automatically to the CLI config. If your config was created in an earlier version, see the "Add CREATE RUNS scope to config" section below.

• BaseSpace CLI requires familiarity with operating in a command-line environment.

  • Windows users can use either the built-in Windows command line by running cmd.exe or Windows PowerShell.

  • Mac OS X users can use the built-in Terminal program.

  • Linux users in a GUI environment should open the terminal program appropriate to their distribution.

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.

Uploading a run with BaseSpace 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: NovaSeq6000, NovaSeqX, NovaSeqXPlus

  • Note: NovaSeqX/XPlus runs are uploaded to ICA v2 but are visible in BSSH

• NextSeq family: NextSeq, NextSeqDx, NextSeq1000, NextSeq2000

• Other instruments: MiniSeq, MiSeq, MiSeqDx, iSeq100

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

Platform-Specific Tips

• Windows: Invoking BaseSpace CLI with "bs" from the command line only works if the bs.exe file has been added to the PATH in the Windows system environment variables. Otherwise the full path to the CLI executable file should be provided. Both the path to bs.exe and the run folder can be auto-filled by dragging-and-dropping the executable and run folder from the desktop into the Windows command line or PowerShell window.

• Mac OS X: Adding the BaseSpace CLI binary to the path $HOME/bin/bs should allow the program to be invoked from the command line using "bs". Otherwise the path to the CLI binary should be provided. When using Terminal if you are in the same directory as the CLI binary you can invoke the program with "./bs". Otherwise both the path to the bs binary and the run folder can be auto-filled by dragging-and-dropping the binary and run folder from the desktop into Terminal window.

• Linux: Adding the BaseSpace CLI binary to the path $HOME/bin/bs should allow the program to be invoked from the command line using "bs". Otherwise the path to the CLI binary should be provided. From the command prompt if you are in the same directory as the CLI binary you can invoke the program with "./bs". If you are using a GUI for Linux, your distribution may allow both the path to the bs binary and the run folder to be auto-filled by dragging-and-dropping the binary and run folder from the desktop into the command prompt window.

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.

Add CREATE RUNS scope to config

Uploading a run folder to BaseSpace Sequence Hub with BaseSpace CLI requires the authentication scope CREATE RUNS. As of version 1.2.1 BaseSpace CLI automatically adds CREATE RUNS to your scopes on config creation after authentication.

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:

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