RAFT CLI reference

LENS is run through RAFT, so every command below is a raft subcommand. This page covers the options that matter when running LENS; raft <command> --help is always authoritative and lists a few options not repeated here.

Note

RAFT is a general workflow manager and supports workflows other than LENS. For RAFT itself, see useraft.io.

Getting started

Command

Purpose

raft setup

Create the RAFT root directory structure and configuration. Run once after installing. --default places everything under the current working directory.

raft install-dependencies

Install RAFT’s system dependencies (Apptainer/Singularity, Nextflow, Java, and wget) on demand, rather than waiting to be prompted during a run. Lists every dependency and where it was found, installs the missing ones, then runs Nextflow once so it downloads its own runtime before your first LENS run. --yes skips the confirmation prompt for scripted setup. Each dependency reports its own progress line; add -V to stream package manager output.

raft --version

Print the RAFT version. LENS 1.9.3 needs v1.5.0 or newer.

raft available-workflows

List the off-the-shelf workflows RAFT can run.

raft available-workflow-profiles --workflow lens --version 1.9.3

List the configuration profiles available for a workflow version. Accepts --species and -i/--input-data (default fastqs), which select the workflow configuration the profiles are read from. See Running LENS using RAFT.

Running a workflow

raft run both creates and runs a project. Given an existing --project-id it re-runs that project instead, and --workflow and --version are then optional.

Core options

Option

Meaning

-p, --project-id

Project identifier. Required.

-w, --workflow

Workflow to run (lens).

-v, --version

Workflow version (1.9.3).

-m, --manifest

Manifest file. See Manifest specifications.

-s, --species

human (default) or mouse. Mouse runs require MHC alleles in the manifest.

-i, --input-data

Starting data type, e.g. fastqs or bams.

--workflow-profile

Apply a named profile (standard, stringent). Without this, RAFT opens the Config Generator.

-d, --dataset

Dataset key used to bootstrap a project through dataset_prep, as an alternative to --manifest (for example HugoLo_IPRES_2016).

-up, --user-params

Override an individual workflow parameter. See Overriding individual workflow parameters below.

Overriding individual workflow parameters

-up / --user-params sets a single workflow parameter without going through the Config Generator. It is available on raft run, raft run-ots, and raft run-demo:

raft run --project-id my-project \
          --workflow lens \
          --version 1.9.3 \
          --manifest my_manifest.tsv \
          --user-params some_parameter=some_value

RAFT applies this by rewriting the project’s workflow/main.nf in place, replacing the value on the line that assigns that parameter. A value containing a colon is treated as a comma-separated list of key:value pairs and written as a Groovy list of quoted pairs; any other value is written as a single-quoted string.

Warning

Pass the flag once per parameter. Because it accepts multiple words but only the first is read, writing two assignments after a single -up applies the first and silently ignores the rest:

# WRONG -- second_param is silently ignored
raft run ... --user-params first_param=a second_param=b

# RIGHT -- repeat the flag
raft run ... --user-params first_param=a --user-params second_param=b

Two further limitations are worth knowing:

  • The parameter must already be assigned in main.nf. If nothing matches, no line is added and the override silently does nothing, so check the spelling against the generated main.nf.

  • The match is an unanchored search for the assignment text <name> =, so a name that is a substring of another parameter can rewrite the wrong line. Use the full parameter name.

Because the edit is written into the project, it persists for later reruns of that project until it is changed again. For anything beyond a parameter or two, prefer the Config Generator or a workflow profile. See Running LENS using RAFT.

Resources and scaling

Option

Meaning

--max-cpus, --max-cpu

Maximum CPUs available to the workflow, passed through as --max_cpus.

--max-mem

Maximum memory available to the workflow.

--no-scaling

Disable RAFT’s automatic per-sample resource scaling. Scaling normally grows requests for larger samples and on retries.

--resource-label

Resource label applied to submitted jobs.

--profile

Nextflow execution profile, e.g. slurm. This selects where jobs run and is unrelated to --workflow-profile.

--nextflow-version

Override the Nextflow version RAFT enforces for this run. RAFT still exports the value as NXF_VER.

Controlling what runs

Option

Meaning

--setup-only

Create or update the project files and modules without launching Nextflow. Useful for editing workflow/nextflow.config before running. This is not a no-write dry run; it does modify the project.

--skip-module-fetches

Stop before module loading. Implies --setup-only.

--skip-downloads

Skip reference and FASTQ downloads.

--no-resume

Do not use Nextflow’s -resume. By default an existing project resumes.

-k, --keep-previous-outputs

Do not remove the previous run’s outputs before running.

--delete-intermediates

Remove trimmed FASTQs and BAMs once downstream processes have consumed them. Intermediates are kept by default; see Running LENS using RAFT.

--include-all-samples

Set every *include_all_samples parameter to TRUE, retaining samples that group-size filtering would otherwise drop.

-n, --nf-params

Extra parameter string passed straight to Nextflow.

--edit-manifest

Open the manifest in the Manifest Generator before running.

-r, --no-reports

Do not launch the report viewer when the run finishes.

--show-all-processes

Show every process in the console output rather than a summary.

Cloud and hybrid

See Running LENS using RAFT for how these combine.

Option

Meaning

--bucket

Single bucket for all RAFT data. Cannot be combined with --project-bucket or --references-bucket.

--project-bucket

Per-project bucket.

--references-bucket

Bucket holding reference files.

--fastqs-bucket

Bucket to discover FASTQs in. Requires another bucket-routing option.

--metadata-bucket

Bucket to discover metadata in. Requires another bucket-routing option.

Inputs, references, and validation

Command

Purpose

raft manifest-template

Write a starter manifest. --no-examples gives a header-only file; --species mouse emits mouse-appropriate example alleles.

raft check-manifest -m <FILE>

Validate a manifest before running. Checks required columns, allowed values, Run_Name prefixes, Alleles formatting, and cross-sample HLA consistency.

raft download-refs -w lens -v 1.9.3 -s human

Download a workflow’s references into the shared references directory without creating a project. --workflow, --version, --species, and -i/--input-data (default fastqs) together select which workflow configuration the reference list is read from, so pass the same values you intend to run with.

raft stage-refs -w lens -v 1.9.3 --references-bucket <URL>

Stage those same workflow-declared references straight into a bucket cache, plus RAFT’s shared directory under shared/. Use before a hybrid or cloud run so the first run does not pay for reference staging.

raft stage-fastqs -m <FILE> --fastqs-bucket <URL>

Upload the FASTQs named by a manifest into a bucket cache. Independent of any project or workflow. RAFT looks for the files in --fastq-dir when given, otherwise beside the manifest and then in the configured RAFT FASTQ directory. --sub-dir stages into a subdirectory, which is useful when one cache holds several cohorts, and --dry-run reports what would be staged. Pass the resulting URL to raft run as --fastqs-bucket.

raft available-datasets

List the off-the-shelf datasets available to you, with the name to pass to --dataset. --json emits machine-readable output. Needs network access to the dataset-prep repositories.

raft download-dataset -d <DATASET>

Download an off-the-shelf dataset’s FASTQs, build its public metadata, and generate its RAFT manifest, without creating a project. FASTQs land in <fastqs-dir>/<DATASET> and metadata in <metadata-dir>/<DATASET>; --fastq-dir and --metadata-dir override both. --skip-fastqs prepares metadata only. Manifest generation runs the dataset’s R prep script under Apptainer, so it needs a container runtime; --skip-manifest stops before that step.

raft load-reference

Load additional reference files or directories into a project.

raft load-metadata

Load metadata files into a project.

raft load-dataset -p <ID> -d <DATASET>

Bootstrap a dataset-prep repository into an existing project, wiring the dataset’s prep_dataset workflow into the project’s main.nf.

raft update-mounts -p <ID> -d <DIR>

Update mounts.config with symlinked inputs from a directory. Needed when inputs live outside the RAFT root, since containers only see bound paths.

Inspecting and reporting

Command

Purpose

raft project-status -p <ID>

Summarise a project’s state. --json emits machine-readable output.

raft generate-reports -p <ID>

Launch the report viewer. --demo opens a demonstration report; --no-load starts the viewer without preloading a project.

raft list-steps

List the processes and workflows a module provides.

Note

On a remote machine the viewer and the other web tools print a http://localhost:<port> address instead of opening a browser. See accessing RAFT’s web tools over SSH.

Project management

Command

Purpose

raft init-project -p <ID>

Create an empty project without running a workflow.

raft package-project / raft load-project

Package a project into a .rftpkg and load one elsewhere. Used to move an analysis between systems with its provenance intact.

raft push-project

Push a project to a configured repository.

raft rename-project

Rename a project. Both --project-id and --new-id are required.

raft copy-parameters

Copy parameters between projects, or from a configuration file.

raft update-parameters

Update parameters and containers from a user-supplied config file.

raft update-modules

Pull the latest commits for each module in a project.

Global options

These work with any subcommand.

Option

Meaning

-V, --verbose

Increase verbosity, including debug output.

-q, --silent

Suppress informational output; show errors only.

--bypass-dependencies

Skip the system dependency checks for Apptainer/Singularity, wget, Nextflow, and Java. Intended for advanced cases; some features will not work without those tools.