Commands Reference¶

Complete reference for all flow CLI commands.

Quick Start¶

After logging in, select a default project to simplify all commands:

# Login
flow login --token YOUR_PAT_TOKEN

# Select default project (interactive)
flow config select-project

# Now all commands work without -p flag
flow files ls
flow orders list
flow runs list

Authentication¶

Authenticate with the Flow platform.

flow login [OPTIONS]

Option	Description
`-e, --email`	Email address (or set `FLOW_EMAIL`)
`-p, --password`	Password (or set `FLOW_PASSWORD`)
`--token`	PAT token for authentication (recommended)

Examples:

# Login with PAT token (recommended)
flow login --token YOUR_PAT_TOKEN

# Login with email/password
flow login -e your@email.com -p yourpassword

# Interactive login (prompts for credentials)
flow login

logout¶

Clear stored credentials.

flow logout

status¶

Check authentication status.

flow status

Configuration¶

config show¶

Display current configuration including selected project.

flow config show

Output:

Current Project Context
  Organization: Intelliseq
  Project: Demo Project
  Project ID: abc123-def456-...

Setting          Value                                Source
────────────────────────────────────────────────────────────
environment      dev                                  config file
file_url         https://files.flow.labpgx.com        config file
compute_url      https://compute.flow.labpgx.com      config file
admin_url        https://admin.flow.labpgx.com        config file
miner_url        https://miner.flow.labpgx.com        config file

config env¶

Set or show the current environment.

flow config env [ENVIRONMENT]

Environment	Description
`prod`	Production (iflow.intelliseq.com)
`stg`	Staging (stg.iflow.intelliseq.com)
`dev`	Development (flow.labpgx.com)

Examples:

# Show current environment
flow config env

# Switch to production
flow config env prod

# Switch to dev
flow config env dev

Note

Switching environments clears the project context. Run flow config select-project after switching.

config select-project¶

Select default project for all commands.

flow config select-project [PROJECT_ID]

Interactive selection:

flow config select-project

Output:

Available Projects

Intelliseq
  [1] Demo Project
  [2] Clinical Lab

Partner Org
  [3] Research Project

Enter project number (or 'q' to cancel): 1

Selected project: Demo Project
  Organization: Intelliseq
  Project ID: abc123-def456-...
  Bucket: iflow-org-intelliseq-proj-demo

You can now run commands without specifying -p/--project.

Direct selection:

flow config select-project abc123-def456-...

config clear-project¶

Clear the saved project selection.

flow config clear-project

config set¶

Set a configuration value.

flow config set <KEY> <VALUE>

Key	Description
`file_url`	File service URL
`compute_url`	Compute service URL
`admin_url`	Admin service URL
`miner_url`	Miner service URL

config reset¶

Reset configuration to defaults.

flow config reset

File Operations¶

All file commands use the selected project by default. Use -p to override.

files ls¶

List files in a project.

flow files ls [PATH]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`PATH`	Path within bucket (default: root)
`--curl`	Output curl command instead of executing

Examples:

# List root directory
flow files ls

# List subdirectory
flow files ls data/samples

# Specify different project
flow files ls -p OTHER_PROJECT data/

files download¶

Download a file.

flow files download <PATH> [-o OUTPUT]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`PATH`	Remote file path relative to bucket
`-o, --output`	Local output path

Examples:

# Download file to current directory
flow files download data/sample.vcf

# Download with custom name
flow files download data/sample.vcf -o my_sample.vcf

files upload¶

Upload a file.

flow files upload <LOCAL_PATH> <REMOTE_PATH>

Option	Description
`-p, --project`	Project ID (optional, uses default)
`LOCAL_PATH`	Local file to upload
`REMOTE_PATH`	Destination path in bucket

Examples:

# Upload file
flow files upload sample.vcf data/sample.vcf

# Upload to different project
flow files upload -p OTHER_PROJECT sample.vcf data/sample.vcf

Order Management¶

Orders represent clinical cases and are managed in the miner-service. All order commands use the selected project by default.

orders list¶

List orders for a project.

flow orders list [OPTIONS]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`--status`	Filter by status
`--priority`	Filter by priority (routine, urgent, stat)
`--limit`	Maximum orders to display (default: 20)
`--curl`	Output curl command instead of executing

Examples:

flow orders list
flow orders list --status created
flow orders list --priority urgent

orders create¶

Create a new clinical order.

flow orders create -n NAME [OPTIONS]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`-n, --name`	Order name (required)
`--accession`	Lab accession number
`--external-id`	External system reference
`--description`	Order description
`--priority`	Priority: routine, urgent, stat (default: routine)
`--indication`	Clinical indication / reason for testing
`--test-type`	Type of genetic test
`--provider`	Ordering provider name
`--facility`	Ordering facility name
`-t, --tag`	Tag for the order (repeatable)

Examples:

# Basic order
flow orders create -n "Patient Case 001"

# Order with clinical details
flow orders create \
  -n "Smith Family Case" \
  --accession ACC-2026-001 \
  --priority urgent \
  --indication "Family history of hereditary cancer" \
  --test-type "Whole Exome Sequencing" \
  --provider "Dr. Jane Smith" \
  --facility "City General Hospital" \
  -t hereditary -t wes

orders get¶

Get order details.

flow orders get <ORDER_ID>

Option	Description
`-p, --project`	Project ID (optional, uses default)
`ORDER_ID`	Order identifier

Output:

Order: Smith Family Case
  ID: abc123-def456-...
  Status: created
  Priority: urgent
  Accession: ACC-2026-001
  Indication: Family history of hereditary cancer
  Test Type: Whole Exome Sequencing
  Provider: Dr. Jane Smith
  Facility: City General Hospital
  Created: 2026-01-13T10:00:00Z
  Tags: hereditary, wes

orders transition¶

Transition order to a new status.

flow orders transition <ORDER_ID> <STATUS>

Option	Description
`-p, --project`	Project ID (optional, uses default)
`ORDER_ID`	Order identifier
`STATUS`	Target status

Valid statuses: created, analyzing, ready_for_review, reviewed, signed_off, completed, amended, cancelled

Status flow:

created -> analyzing -> ready_for_review -> reviewed -> signed_off -> completed
                                                                        -> amended

Examples:

flow orders transition ORDER_ID analyzing
flow orders transition ORDER_ID ready_for_review
flow orders transition ORDER_ID completed

orders delete¶

Delete an order.

flow orders delete <ORDER_ID>

Prompts for confirmation before deleting.

orders samples¶

List samples in an order.

flow orders samples <ORDER_ID>

orders add-sample¶

Add a sample to an order.

flow orders add-sample <ORDER_ID> <SAMPLE_ID>

orders remove-sample¶

Remove a sample from an order.

flow orders remove-sample <ORDER_ID> <SAMPLE_ID>

Pipeline Management¶

pipelines list¶

List available pipelines.

flow pipelines list

Output:

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

pipelines info¶

Get pipeline details.

flow pipelines info <SLUG>

Argument	Description
`SLUG`	Pipeline identifier

Output:

Pipeline: Hereditary Mock Pipeline
  Slug: hereditary-mock
  Type: direct_wdl
  Container: broadinstitute/cromwell:86
  Tags: wdl, hereditary, mock, cromwell

  Description: Mock hereditary analysis pipeline for WDL/Cromwell testing.

  Required inputs: case_id, child_fastq

Run Management¶

Runs are executed in compute-service and can be associated with orders from miner-service. All run commands use the selected project by default.

runs submit¶

Submit a new pipeline run.

flow runs submit --pipeline SLUG [OPTIONS]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`--pipeline`	Pipeline slug (required)
`-o, --order-id`	Order ID to associate (from miner-service)
`-P, --param`	Parameter in KEY=VALUE format (repeatable)
`-t, --tag`	Tag for the run (repeatable)
`--profile`	Override Nextflow profile
`--watch`	Watch status after submission
`--curl`	Output curl command instead of executing

Examples:

# Simple run
flow runs submit --pipeline wdl-minimal --watch

# Run with parameters (paths are relative to project bucket)
flow runs submit --pipeline hereditary-mock \
  -P case_id=case-001 \
  -P child_fastq=data/R1.fastq.gz \
  -P child_fastq=data/R2.fastq.gz \
  --watch

# Run associated with an order
flow runs submit --pipeline hereditary-mock \
  --order-id ORDER_ID \
  -P case_id=case-001 \
  -P child_fastq=data/R1.fastq.gz \
  -P child_fastq=data/R2.fastq.gz \
  -t clinical -t hereditary \
  --watch

# Full GCS paths also work
flow runs submit --pipeline hereditary-mock \
  -P child_fastq=gs://other-bucket/R1.fastq.gz \
  --watch

File Paths

File paths are automatically resolved relative to your project bucket. Use gs:// prefix for files in other buckets.

runs list¶

List runs for a project.

flow runs list [OPTIONS]

Option	Description
`-p, --project`	Project ID (optional, uses default)
`-o, --order-id`	Filter by order ID
`--limit`	Maximum runs to display (default: 20)

Examples:

# List all runs
flow runs list

# List runs for a specific order
flow runs list --order-id ORDER_ID

runs status¶

Get run details.

flow runs status <RUN_ID>

Argument	Description
`RUN_ID`	Run identifier

Output:

Run: hereditary-mock-20260113-100000
  ID: abc123-def456-...
  Status: succeeded
  Pipeline ID: pipeline-id-...
  Order ID: order-id-...
  Profile: local
  Created: 2026-01-13T10:00:00Z
  Started: 2026-01-13T10:01:00Z
  Finished: 2026-01-13T10:05:00Z
  Output: gs://bucket/outputs/hereditary-mock-20260113-100000/
  Parameters:
    case_id: case-001
    child_fastq: ['gs://bucket/R1.fastq.gz', 'gs://bucket/R2.fastq.gz']
  Tags: clinical, hereditary

runs watch¶

Watch run until completion.

flow runs watch <RUN_ID> [--interval SECONDS]

Option	Description
`RUN_ID`	Run identifier
`--interval`	Polling interval in seconds (default: 10)

Output:

[10:00:15] Status: queued
[10:01:00] Status: running
           Started: 2026-01-13T10:00:55Z
[10:05:00] Status: succeeded
           Finished: 2026-01-13T10:04:50Z

Run completed successfully!
Output: gs://bucket/outputs/hereditary-mock-20260113-100000/

runs cancel¶

Cancel a running or queued run.

flow runs cancel <RUN_ID>

Prompts for confirmation before cancelling.

Global Options¶

Option	Description
`--version`	Show version and exit
`--help`	Show help message

API Debugging with --curl¶

Most commands support a --curl flag that outputs the equivalent curl command instead of executing the API call. This is useful for:

Debugging - See exactly what API call would be made
Scripting - Copy curl commands for use in shell scripts
Learning - Understand the underlying REST API

Supported commands:

Command Group	Commands with --curl
`files`	`ls`, `download`, `upload`
`orders`	`list`, `create`, `get`, `transition`, `delete`, `samples`, `add-sample`, `remove-sample`
`runs`	`list`, `submit`, `status`, `cancel`, `watch`
`pipelines`	`list`, `info`
`config`	`select-project`

Examples:

# Get curl command for listing pipelines
flow pipelines list --curl

# Output:
# curl \
#   -s \
#   -H \
#   Authorization: Bearer YOUR_TOKEN \
#   https://compute.flow.labpgx.com/api/v1/pipelines

# Get curl command for creating an order
flow orders create -n "Test Order" --priority urgent --curl

# Output:
# curl \
#   -s \
#   -X \
#   POST \
#   -H \
#   X-Project-ID: your-project-id \
#   -H \
#   Authorization: Bearer YOUR_TOKEN \
#   -H \
#   Content-Type: application/json \
#   -d \
#   {
#     "name": "Test Order",
#     "priority": "urgent"
#   } \
#   https://miner.flow.labpgx.com/api/v1/orders

# Get curl command for submitting a run
flow runs submit --pipeline hereditary-mock \
  -P case_id=test-001 \
  -P child_fastq=data/R1.fastq.gz \
  --curl

# Output shows the full API call with resolved GCS paths

Token Included

The --curl output includes your current access token in the Authorization header, making the commands ready to execute.

Environment Variables¶

Variable	Description
`FLOW_EMAIL`	Default email for login
`FLOW_PASSWORD`	Default password for login
`FLOW_FILE_URL`	Override file service URL
`FLOW_COMPUTE_URL`	Override compute service URL
`FLOW_ADMIN_URL`	Override admin service URL
`FLOW_MINER_URL`	Override miner service URL

Getting Help¶

# General help
flow --help

# Command group help
flow config --help
flow orders --help
flow runs --help

# Command-specific help
flow config select-project --help
flow orders create --help
flow runs submit --help

Commands Reference¶

Quick Start¶

Authentication¶

login¶

logout¶

status¶

Configuration¶

config show¶

config env¶

config select-project¶

config clear-project¶

config set¶

config reset¶

File Operations¶

files ls¶

files download¶

files upload¶

Order Management¶

orders list¶

orders create¶

orders get¶

orders transition¶

orders delete¶

orders samples¶

orders add-sample¶

orders remove-sample¶

Pipeline Management¶

pipelines list¶

pipelines info¶

Run Management¶

runs submit¶

runs list¶

runs status¶

runs watch¶

runs cancel¶

Global Options¶

API Debugging with --curl¶

Environment Variables¶

Getting Help¶