Instructions for using BaseSpace CLI on Windows to upload runs

The BaseSpace Command Line Interface (BaseSpace CLI) can be used to perform many associated functions in BaseSpace Sequence Hub such as uploading/downloading run folders, FASTQ files, launching apps, terminating analyses, and more.

The broad overview of steps are as follows:

1. Download BaseSpace CLI.

2. Open/Launch BaseSpace CLI.

3. Authenticate into the desired BaseSpace account.

4. Download FASTQs.

5. Upload a run.

Installing and authenticating the BaseSpace CLI

For specific instructions on each step, see below or watch this video:

1. Download BaseSpace CLI

• The download link can be found on the CLI Overview webpage.

• The Windows version of BaseSpace CLI will download as an executable (.exe) file.

1. Open/Launch BaseSpace CLI

• To open BaseSpace CLI, open a file explorer and navigate to where the bs.exe file is stored.

• In the file explorer address bar, type cmd and press the Enter key on the keyboard to open up the command line window.

• This opens a window known as the command line interface.

  • 
  • 
  • 

1. Authenticate BaseSpace CLI

• Use the command bs auth or ./bs auth to generate a BaseSpace CLI authentication link.

  • If the above commands do not work, try using bs.exe instead of just bs

  • 
  • If the command is successful, a link will appear in the command window.

  • If the commands work but the command line prompts an error stating "Unable to authenticate" try using the command bs auth -f to overwrite or force the authentication.

• Copy and paste the link into a web browser and log into the desired BaseSpace account to complete the authentication process.

  • Note: If uploading to a Workgroup (Professional or Enterprise), be sure to switch to the Workgroup prior to pasting the link into the browser to authenticate.

  • 
  • Note: If the link was not used to authenticate within one minute, the user may encounter a timeout error. If a timeout error occurs prior to successful authentication, simply re-enter the command to authenticate.

  • 
• After successful authentication, a new line should populate stating Welcome Username. To confirm authentication was successful, run the command bs whoami.

  • 
  • Once the Command Line Interface has been successfully authenticated, many actions can be performed.

How to Upload a Run Folder

1. Confirm that all run files necessary for upload are present and compiled into the folder that being used during upload.

• These can be uploaded from the original run folder or copied to a new folder containing only the necessary files.

• The 5 folders/files listed below are the bare minimum files required for FASTQ generation after the upload completes:

  • InterOp (folder)

  • RunInfo.xml

  • RunParameters.xml

  • SampleSheet.csv

  • Data (folder)

    • Confirm that the data folder has all of the appropriate basecall files (bcl) as the bcl files are translated into FASTQ files during FASTQ generation.

    • To check if the basecall files are present, check the following file path: data > intensities > basecalls

1. Construct the command to be used for run upload:

• The base command to upload a run folder with BaseSpace CLI is as follows

  • bs upload run -n {RunName} -t {InstrumentType} {PathToRunFolder}

• Replace the values in brackets with user specific data:

• {RunName} = The desired run name to appear in BaseSpace.

  • The run name used should contain only alphanumerics, no spaces or special characters.

• {InstrumentType} = the type of instrument on which the run was performed.

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

  • HiSeq family	HiSeq1000, HiSeq1500, HiSeq2000, HiSeq2500, HiSeq3000, HiSeq4000, HiSeqX
    NovaSeq family	NovaSeq6000
    NextSeq family	NextSeq (note: refers to the NextSeq 500/550), NextSeq1000, NextSeq2000
    Other Instruments	MiniSeq, MiSeq, iSeq100

• {PathToRunFolder} = the file pathway to the run folder to be uploaded

  • The file path for the run folder can be dragged and dropped into the command line interface directly or copy and pasted from the file explorer address bar.

  • If there are spaces in the run folder path, include quotation marks around the file path.

• An example of a complete valid upload command is:

  • bs upload run -n UploadedRun -t MiSeq C:\Illumina\MiSeqOutput\20220315\_M12345\_LMNO\_45974309404

• Important Platform-Specific Considerations:

  • If uploading directly from the MiSeq, use the MiSeqOutput or MiSeqAnalysis folder as the MiSeqTemp does not contain BCL files.

  • If uploading directly from the NovaSeq 6000, the RunParameters.xml and SampleSheet.csv files are stored in a different folder on the instrument.

    • To make sure all necessary components are uploaded successfully, include a flag to add the Sample Sheet and RunParameters.xml files as specified below, inputting the information specific to the run folder:

    • The sample sheet flag will look like: --samplesheet C:\ProgramData\Illumina\NovaSeq\NovaSeqTemp\{run folder}\SampleSheet.csv

    • The RunParameters.xml flag will look like: --run-parameters C:\ProgramData\Illumina\NovaSeq\NovaSeqTemp\{run folder}\RunParameters.xml

    • The whole command strung together will look like: bs upload run -n {run name} -t NovaSeq6000 --samplesheet C:\ProgramData\Illumina\NovaSeq\NovaSeqTemp\{run folder}\SampleSheet.csv --run-parameters C:\ProgramData\Illumina\NovaSeq\NovaSeqTemp\{run folder}\RunParameters.xml Z:\outputfolder\{run folder}

  • If uploading directly from the NovaSeq X Series, see Using the BaseSpace Command Line Interface (CLI) Tool on the NovaSeq X Series.

1. Run the command.

• Copy and paste the command into the Command Line Interface and press Enter to start the run upload.

• Be sure to leave the CLI window open until the run upload has completed successfully.

For further information, see Knowledge Base articles How to use BaseSpace Command Line Interface (CLI) to upload run folders to BaseSpace Sequence Hub and Uploading Runs BaseSpace Command Line Interface (CLI) Video.

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