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 |
|---|---|
|
Create the RAFT root directory structure and configuration. Run once
after installing. |
|
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. |
|
Print the RAFT version. LENS 1.9.3 needs v1.5.0 or newer. |
|
List the off-the-shelf workflows RAFT can run. |
|
List the configuration profiles available for a workflow version. Accepts
|
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 |
|---|---|
|
Project identifier. Required. |
|
Workflow to run ( |
|
Workflow version ( |
|
Manifest file. See Manifest specifications. |
|
|
|
Starting data type, e.g. |
|
Apply a named profile ( |
|
Dataset key used to bootstrap a project through |
|
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 generatedmain.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 |
|---|---|
|
Maximum CPUs available to the workflow, passed through as |
|
Maximum memory available to the workflow. |
|
Disable RAFT’s automatic per-sample resource scaling. Scaling normally grows requests for larger samples and on retries. |
|
Resource label applied to submitted jobs. |
|
Nextflow execution profile, e.g. |
|
Override the Nextflow version RAFT enforces for this run. RAFT still
exports the value as |
Controlling what runs
Option |
Meaning |
|---|---|
|
Create or update the project files and modules without launching
Nextflow. Useful for editing |
|
Stop before module loading. Implies |
|
Skip reference and FASTQ downloads. |
|
Do not use Nextflow’s |
|
Do not remove the previous run’s outputs before running. |
|
Remove trimmed FASTQs and BAMs once downstream processes have consumed them. Intermediates are kept by default; see Running LENS using RAFT. |
|
Set every |
|
Extra parameter string passed straight to Nextflow. |
|
Open the manifest in the Manifest Generator before running. |
|
Do not launch the report viewer when the run finishes. |
|
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 |
|---|---|
|
Single bucket for all RAFT data. Cannot be combined with
|
|
Per-project bucket. |
|
Bucket holding reference files. |
|
Bucket to discover FASTQs in. Requires another bucket-routing option. |
|
Bucket to discover metadata in. Requires another bucket-routing option. |
Inputs, references, and validation
Command |
Purpose |
|---|---|
|
Write a starter manifest. |
|
Validate a manifest before running. Checks required columns, allowed
values, |
|
Download a workflow’s references into the shared references directory
without creating a project. |
|
Stage those same workflow-declared references straight into a bucket
cache, plus RAFT’s shared directory under |
|
Upload the FASTQs named by a manifest into a bucket cache. Independent
of any project or workflow. RAFT looks for the files in |
|
List the off-the-shelf datasets available to you, with the name to pass
to |
|
Download an off-the-shelf dataset’s FASTQs, build its public metadata,
and generate its RAFT manifest, without creating a project. FASTQs land
in |
|
Load additional reference files or directories into a project. |
|
Load metadata files into a project. |
|
Bootstrap a dataset-prep repository into an existing project, wiring the
dataset’s |
|
Update |
Inspecting and reporting
Command |
Purpose |
|---|---|
|
Summarise a project’s state. |
|
Launch the report viewer. |
|
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 |
|---|---|
|
Create an empty project without running a workflow. |
|
Package a project into a |
|
Push a project to a configured repository. |
|
Rename a project. Both |
|
Copy parameters between projects, or from a configuration file. |
|
Update parameters and containers from a user-supplied config file. |
|
Pull the latest commits for each module in a project. |
Global options
These work with any subcommand.
Option |
Meaning |
|---|---|
|
Increase verbosity, including debug output. |
|
Suppress informational output; show errors only. |
|
Skip the system dependency checks for Apptainer/Singularity, wget, Nextflow, and Java. Intended for advanced cases; some features will not work without those tools. |