Skip to content

Your First Workflow

This guide walks you through running your first bioinformatics pipeline on Flow using the CLI — from patient registration through sample upload to analysis and results.

Prerequisites

Before starting, ensure you have:

  1. An account on Flow (contact your administrator)
  2. Python 3.11 or later installed
  3. Access to a project with cloud credentials configured

Complete CLI Walkthrough

Step 1: Get Your Access Token

  1. Navigate to Admin Console > Settings > CLI Tokens
  2. Log in with your credentials
  3. Click Create Token
  4. Copy the generated token

Step 2: Install and Configure

# Install the CLI
pip install intelliseq-iflow

# Interactive setup (recommended for first time)
iflow configure

Or configure manually:

# Login with your token
iflow login --token YOUR_TOKEN_HERE

# Select your project
iflow config select-project

Output:

Using Personal Access Token...
Successfully logged in with PAT!

Found 2 projects.
Run iflow config select-project to choose one.

Step 3: View Available Pipelines

iflow pipelines list

Output:

SLUG                      VERSION    NAME                      MODE
-------------------------------------------------------------------------------------
hereditary-mock           1.0.0      Hereditary Mock Pipeline  direct_wdl
wdl-minimal               1.0.0      WDL Minimal Pipeline      direct_wdl
nextflow-minimal          1.0.0      nextflow-minimal          container_entrypoint
nfcore-demo               1.0.0      nf-core/demo              direct_nextflow

Get details about a specific pipeline:

iflow pipelines describe hereditary-mock

Step 4: Create a Subject (Patient)

Register the patient in the system:

iflow subjects create -n "Patient-001" \
  -P sex=female \
  -P diagnosis="Hereditary cancer screening"

Output:

Subject created successfully!
  Subject ID: Patient-001
  Sex: female

Step 5: Create a Sample

Link a biological sample to the subject:

iflow samples create \
  --subject-id "Patient-001" \
  -n "NA12878" \
  -P sample_type=germline \
  -P tissue=blood

Output:

Sample created successfully!
  Sample ID: NA12878
  Type: germline

Step 6: Upload Sample Data

Upload a VCF file to the sample's path:

# Create minimal test VCF file
echo -e "##fileformat=VCFv4.2\n#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO\nchr1\t100\t.\tA\tG\t30\tPASS\t." | bgzip -c > sample.vcf.gz

# Upload to sample (auto-constructs path: samples/na12878/uploads/sample.vcf.gz)
iflow files upload sample.vcf.gz --sample-id "NA12878"

Verify the upload:

iflow files ls samples/na12878/uploads/

Step 7: Submit an Analysis

Submit an analysis linked to the sample created in Step 5 (file paths are relative to your project bucket):

iflow analyses submit \
  --pipeline hereditary-mock \
  -n "my-first-analysis" \
  --sample-id "NA12878" \
  -P subject_id=Patient-001 \
  -P panel_name="Primary Immunodeficiency" \
  -P snv_vcf_gz=samples/na12878/uploads/sample.vcf.gz \
  -P name="Jane" \
  -P surname="Smith" \
  -P sex="F" \
  --watch
  • -n sets a custom analysis ID (auto-generated if omitted)
  • --sample-id links this analysis to the sample and automatically resolves the subject
  • --watch monitors progress until completion
Analysis submitted successfully!
  Analysis ID: my-first-analysis
  Status: queued

Watching analysis status (Ctrl+C to stop)...
[11:20:53] Status: queued
[11:23:35] Status: running
           Started: 2026-01-16T11:22:30Z
[11:29:46] Status: succeeded

Analysis completed successfully!
Output: analyses/my-first-analysis/

Step 8: View Outputs

Use the analysis name from Step 7 to view outputs:

iflow analyses outputs my-first-analysis

Output:

NAME                 TYPE        PATH
--------------------------------------------------------------------------------
reports_pdf          Array[File] wdl-results/.../mock_report.pdf
top20_tsv            File        wdl-results/.../top20.tsv
top20_vcf_gz         File        wdl-results/.../top20.vcf.gz
annotated_vcf_gz     File        wdl-results/.../annotated.vcf.gz
reports_docx         Array[File] wdl-results/.../report.docx

Step 9: Download Results by Name

Download outputs using their semantic names:

# Download the PDF report
iflow analyses outputs my-first-analysis -d reports_pdf -o report.pdf

Output:

Downloading reports_pdf...
Downloaded: report.pdf

Verify the download:

ls -la report.pdf

Quick Reference

Step Command
Configure iflow configure
Login iflow login --token TOKEN
Select project iflow config select-project
List pipelines iflow pipelines list
Create subject iflow subjects create -n "ID" -P sex=female
Create sample iflow samples create --subject-id ID -n "ID" -P sample_type=germline
Upload file iflow files upload LOCAL_FILE --sample-id SAMPLE_ID
Submit analysis iflow analyses submit --pipeline SLUG -n NAME --sample-id ID --watch
View outputs iflow analyses outputs NAME
Download output iflow analyses outputs NAME -d OUTPUT -o FILE

Next Steps