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:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ raft available-modules

Load a module into an existing project:

.. code-block:: console

  $ 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``:

.. code-block:: console

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

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

.. code-block:: console

  $ 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:

.. code-block:: console

  $ 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:

.. code-block:: console

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

Filter for a specific step name:

.. code-block:: console

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

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

.. code-block:: console

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

Emit JSON for scripts or UI tooling:

.. code-block:: console

  $ 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``:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ 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:

.. code-block:: console

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

Update a subset of modules with ``--modules``:

.. code-block:: console

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

Run the assembled workflow
--------------------------

Run the project after manual assembly with:

.. code-block:: console

  $ 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.