Comment on page

Step By Step Instructions on Uploading a Run Using BaseSpace CLI on Windows

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. To upload run folders after run completion, follow these steps:
The broad overview of steps are as follows:
  1. 1.
    Download BaseSpace CLI
  2. 2.
    Open/Launch BaseSpace CLI
  3. 3.
    Authenticate into the desired BaseSpace account
  4. 4.
    Upload the run
For specific instructions on each step, see below: 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. 2.
    Open/Launch BaseSpace CLI
    1. 1.
      To open BaseSpace CLI, open a file explorer and navigate to where the bs.exe file is stored.
    2. 2.
      In the file explorer address bar, type "cmd" and press the 'enter' key on the keyboard to open up the command line window.
    3. 3.
      This should open up a window known as the command line interface.
3. Authenticate BaseSpace CLI 1. Use command bs auth or ./bs auth to authenticate BaseSpace CLI. * If the above commands do not work, try using "bs.exe" instead of just "bs"
  1. 1.
    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.
  • If successful, a link will appear in the command window.
  • Copy and paste the link into a web browser and log in to the desired BaseSpace account to complete the authentication process.
    • Note: If you are uploading to a Workgroup (Professional or Enterprise), be sure to switch to the Workgroup prior to pasting the link into the browser to authenticate.
2. 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.
3. 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 authenticated successfully, proceed through the steps below to **upload the 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: 1. InterOp (folder) 2. RunInfo.xml 3. RunParameters.xml 4. SampleSheet.csv 5. 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
  • Important Considerations for run files:
    • 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 file is stored in a different folder on the instrument. - To ensure 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 your 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}
  1. 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}
  • The values in purple should be replaced with user specific data 1. {RunName} = The desired run name to appear in BaseSpace * The run name used should contain only alphanumerics, no spaces or special characters. 2. {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, NovaSeqX, NovaSeqXPlus Note: NovaSeq X/X Plus runs are uploaded to ICA v2 but are visible in BSSH
    NextSeq family
    NextSeq, NextSeqDx, NextSeq1000, NextSeq2000
    Other Instruments
    MiniSeq, MiSeq, MiSeqDx, iSeq100
    3. **{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\MiSeq\20220315\_M12345\_LMNO\_45974309404**
  1. 3.
    Run the command
  • Copy and paste the command into the Command Line Interface and hit ‘enter’ to start the run upload.
  • Be sure to leave the CLI window open until the run upload has completed successfully.
For further information, search for 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 [email protected].
© 2023 Illumina, Inc. All rights reserved. All trademarks are the property of Illumina, Inc. or their respective owners. Trademark information: Privacy policy: