Manual workflow and module assembly

Most users should run off-the-shelf workflows with raft run. The commands on this page are lower-level tools for developers and advanced users who need to inspect, assemble, or modify a RAFT project manually.

Initialize a project manually

raft init-project initializes a project from a local initialization config:

$ raft init-project \
    --project-id my-project \
    --init-config .init.cfg

This creates the project directory, standard subdirectories, workflow/, workflow/main.nf, workflow/nextflow.config, workflow/mounts.config, .raft/auto.raft, and the local package repository directory.

Off-the-shelf workflows usually call this internally, so most users do not need to run it directly.

Load metadata and references

raft load-metadata loads a metadata file from the configured global metadata directory into a project:

$ raft load-metadata \
    --project-id my-project \
    --file my_manifest.tsv

raft load-reference does the same for files under the configured global references directory:

$ raft load-reference \
    --project-id my-project \
    --file genome.fa \
    --sub-dir hg38

Both commands support --mode symlink and --mode copy. Symlink mode also updates workflow/mounts.config so Singularity or Apptainer can see the linked file target.

Update mounts

Use raft update-mounts when a project contains symlinks to files outside the project directory and those targets need to be visible inside containers:

$ raft update-mounts \
    --project-id my-project \
    --dir /path/to/project/inputs

RAFT scans the directory recursively, resolves symlink targets, and adds the needed host paths to workflow/mounts.config.

Discover and load modules

List discoverable modules:

$ raft available-modules

Load a module into an existing project:

$ raft load-module \
    --project-id my-project \
    --module bwa

By default, RAFT searches configured module repositories, clones the requested module into workflow/modules/, applies any module config to workflow/nextflow.config, and recursively loads dependencies. Use --no-deps to skip dependency loading.

Select branches with --branches:

$ raft load-module \
    --project-id my-project \
    --module bwa \
    --branches main

You can assign branches per module with comma-separated module:branch pairs:

$ raft load-module \
    --project-id my-project \
    --module alignment \
    --branches alignment:main,bwa:prod,samtools:prod

Inspect module steps

Use raft list-steps to list processes and workflows exposed by loaded modules:

$ raft list-steps --project-id my-project

By default, list-steps prints a compact tab-delimited table with the module, step type, and step name. This command is intended for inspecting module entry points during manual workflow assembly. For large projects, use --module or --step to keep the output focused.

Limit the output to one module:

$ raft list-steps \
    --project-id my-project \
    --module bwa

Filter for a specific step name:

$ raft list-steps \
    --project-id my-project \
    --module bwa \
    --step bwa_mem

Show step metadata from // require: blocks when available:

$ raft list-steps \
    --project-id my-project \
    --module bwa \
    --details

Emit JSON for scripts or UI tooling:

$ raft list-steps \
    --project-id my-project \
    --module bwa \
    --json

--json can be combined with --details.

Add a step to main.nf

Use raft add-step to inject a process or workflow from a loaded module into the project’s workflow/main.nf:

$ raft add-step \
    --project-id my-project \
    --module bwa \
    --step bwa_mem

Use --alias when the same step needs to be included more than once:

$ raft add-step \
    --project-id my-project \
    --module bwa \
    --step bwa_mem \
    --alias bwa_mem_tumor

RAFT makes a main.nf.bak backup before editing main.nf.

Update loaded modules

Pull updates for loaded modules:

$ raft update-modules --project-id my-project

Update a subset of modules with --modules:

$ raft update-modules \
    --project-id my-project \
    --modules bwa,samtools

Run the assembled workflow

Run the project after manual assembly with:

$ raft run-workflow --project-id my-project

For existing projects, raft run --project-id my-project uses the same workflow execution path and is usually preferred.