Submitting Runs¶

Basic usage¶

tracker run SCRIPT [platform flags] [--workflow params]

SCRIPT (required) is either a git URL or a local file path.

Flag convention

Following Nextflow conventions, platform flags use a single dash (-name, -output-dir, -r, -profile) and workflow parameters use double dashes (--outdir, --input). Tracker recognizes its own flags and passes the rest through to the workflow runner unchanged.

Flag namespaces¶

Every argument falls into one of three namespaces:

Namespace	Examples	Who consumes it
Tracker	`-name`, `-output-dir`, `-cluster`, `-labels`, `-notes`, `-runner-*`, `-dry-run`	The Tracker CLI / API. Stripped from the command line before launching the runner.
Workflow runner	`-r`, `-profile`, `-w`, `-c`, `-params-file`, `-resume`	Passed through verbatim to `nextflow` (or the WDL runner). Tracker never inspects them.
Workflow	`--outdir`, `--input`, anything else with a double-dash	Workflow params (`params.*`). Each workflow defines its own.

`-output-dir` and `--outdir` must agree¶

-output-dir (Tracker) and --outdir (workflow) refer to the same S3 path. You only need to specify one — Tracker syncs them. If you supply both and they differ, the CLI rejects the submission rather than silently picking one.

Platform flags¶

Flags recognized by tracker. All are optional unless noted.

Flag	Description	Example
`-output-dir`	S3 output directory. Required — either this or `--outdir` must be provided. See `-output-dir` and `--outdir` must agree.	`-output-dir s3://bucket/output`
`-name`	Custom run name. Auto-generated if omitted.	`-name my-daq-run`
`-cluster`	Target Kubernetes cluster. Falls back to config default.	`-cluster pltf-dev`
`-labels`	Labels for filtering in Tracker. Repeatable.	`-labels team=ngs -labels experiment=v2`
`-notes`	Freeform notes visible in the run detail UI.	`-notes "Testing new ref genome"`
`-params-file`	Path to a workflow params file (local or S3).	`-params-file s3://bucket/params.yaml`
`-resume`	Resume a previous run by session ID.	`-resume 12a3b4c5-...`
`-runner-cpu`	CPU allocation for the runner pod.	`-runner-cpu 4`
`-runner-memory`	Memory allocation for the runner pod.	`-runner-memory 8Gi`
`-runner-image`	Custom runner container image.	`-runner-image 123456.dkr.ecr...`
`-project-dir`	Local project directory. Auto-detected for local scripts.	`-project-dir ./my-pipeline`
`-dry-run`	Print the submission payload without actually running.	`-dry-run`

Any single-dash flags that tracker doesn't recognize (e.g., -r, -profile, -w, -c) are passed through to the workflow runner as-is.

Workflow params¶

Double-dash arguments are passed through to the workflow as parameters (params.*). Each workflow defines its own set of accepted params — check the workflow's documentation for details.

The one param that gets special handling is --outdir: if you specify -output-dir (tracker flag), tracker automatically sets --outdir for the workflow. See -output-dir and --outdir must agree.

Clusters¶

Tracker manages multiple Kubernetes clusters and the web UI shows runs from all of them in one list. Use the -cluster flag to pick a target cluster per submission, or set a default with tracker config set cluster <name>.

A cluster admin must add you to a cluster before you can submit runs there. If you see Access denied to cluster 'pltf-dev' (or any other cluster name) after tracker auth login, ask a cluster admin to grant access.

AWS credentials¶

tracker run uses your ambient AWS credentials to upload local code and params files to S3 before submission. Set AWS_PROFILE to the profile for the target cluster's AWS account before running. For pltf-dev:

export AWS_PROFILE=pltf-dev

Clusters in other AWS accounts require the matching profile for that account. If S3 uploads fail with ExpiredToken or AccessDenied, refresh the SSO session for that profile (aws sso login --profile <name>).

Examples¶

Basic run:

tracker run \
  https://gitlab.natera.com/rd-platform/bioinformatics/infrastructure/nextflow-pipeline-template.git \
  -r master \
  -profile docker,eks,test \
  --outdir s3://natera-platform-sandbox/users/abshah/my-output

Run with labels and notes:

tracker run \
  https://gitlab.natera.com/rd-platform/bioinformatics/infrastructure/nextflow-pipeline-template.git \
  -name my-test-run \
  -r master \
  -profile docker,eks,test \
  -labels team=ngs \
  -notes "Testing new ref genome" \
  --outdir s3://natera-platform-sandbox/users/abshah/my-output \
  --input s3://data/samplesheet.csv

Resume a failed run:

tracker run \
  https://gitlab.natera.com/rd-platform/bioinformatics/infrastructure/nextflow-pipeline-template.git \
  -name my-retry \
  -r master \
  -profile docker,eks,test \
  -resume 12a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c \
  --outdir s3://natera-platform-sandbox/users/abshah/my-output

Dry run (validate without submitting):

tracker run \
  https://gitlab.natera.com/rd-platform/bioinformatics/infrastructure/nextflow-pipeline-template.git \
  -r master \
  -profile docker,eks,test \
  -dry-run \
  --outdir s3://natera-platform-sandbox/users/abshah/my-output