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 and 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

**:*

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. Do not try to run it as a regular application.

2. 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 or bs auth --force 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. To copy the link, highlight it and right click it, then paste it into the browser, do not use Ctrl+C as this will cancel the authentication command.

    • 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 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: Files > Data > Intensities > BaseCalls

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

MiSeq family	MiSeq, MiSeqi100, MiSeqi100Plus, MiSeqDx (RUO mode)
NovaSeq family	NovaSeq5000, NovaSeq6000, NovaSeqX, NovaSeqXPlus, NovaSeq6000Dx (RUO Mode)
NextSeq family	NextSeq (note: refers to the NextSeq 500/550), NextSeq1000, NextSeq2000, NextSeqDx (RUO Mode)
Other Instruments	MiniSeq, 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 SampleSheet.csv and RunParameters.xml files as specified below, inputting the information specific to the run folder:  
    * The SampleSheet.csv 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}

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

2. 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 upload a run to BaseSpace using BaseSpace Command Line Interface (CLI) 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].