How to Download FastQs from BaseSpace

Commands for reviewing and downloading projects, runs, and sample FastQ files using the BaseSpace Sequence Hub CLI.

---

Table of Contents

• Install BaseSpace CLI
• Authenticate
• Check User Info
• Option A: Download by Project
• Option B: Download by Run
• Post-Download Cleanup
• Tips

---

Install BaseSpace CLI

# macOS (Homebrew)
brew tap basespace/basespace && brew install bs-cli

# Linux (manual install)
# Download from: https://developer.basespace.illumina.com/docs/content/documentation/cli/cli-overview

Authenticate

bs auth

This will open a browser window for you to log in and authorize the CLI.

Check User Info

bs whoami

---

Option A: Download by Project

Use this when your FastQs are organized under a Project in BaseSpace (most common for standard sequencing runs that have been analyzed).

1. List available projects

bs list projects

2. List FastQ datasets in a project

bs list datasets --project-id=<ProjectID> --is-type=common.fastq

3. Download FastQs

cd /path/to/projectName

bs download project -i <ProjectID> -o /to/the/out/path/fastqs/ --extension=fastq.gz

💡 For paired-end sequencing, each sample has two FastQ files: Read1 (R1) and Read2 (R2).

4. Move all FastQs into one folder & clean up

# Move all fastq.gz files from subfolders to current directory
mv */*.fastq.gz ./

# Remove empty subfolders
rmdir ./*

---

Option B: Download by Run

Use this when you want to download the raw BCL/FastQ data directly from a sequencing Run — for example, when you need to re-demultiplex or when data hasn't been assigned to a project yet.

1. List available runs

bs list runs

2. Get details of a specific run

bs get run -i <RunID>

3. Download FastQs from a run

bs download run -i <RunID> -o /to/the/out/path/fastqs/ --extension=fastq.gz

4. (Alternative) Download specific samples from a run

If you only need certain samples:

# List samples
bs list biosample

# Download a specific dataset by its ID
bs download dataset -i <DatasetID> -o /to/the/out/path/fastqs/

---

Post-Download Cleanup

After downloading, FastQ files are often nested in subdirectories. Flatten them:

cd /to/the/out/path/fastqs/

# Move all fastq.gz into the current directory
mv */*.fastq.gz ./

# Remove the now-empty subdirectories
rmdir ./*

Tips

• Project vs Run: If you ran a standard pipeline (e.g., DRAGEN, bcl2fastq) on BaseSpace, the resulting FastQs are usually under a Project. If you want the raw output or need to work with unprocessed data, download by Run.

• Large downloads: For large projects/runs, consider using --retry or running inside tmux/screen to avoid interruptions.

• Check disk space before downloading — sequencing runs can be hundreds of GB.

• Verify file integrity after download:

  # Quick check: count files
  ls *.fastq.gz | wc -l
  
  # Check for truncated files using gzip test
  for f in *.fastq.gz; do gzip -t "$f" && echo "$f OK" || echo "$f CORRUPT"; done