Helpful RAFT options
====================

Most off-the-shelf runs only need a project id, workflow, version, and
manifest. The options below are useful when you need more control over how RAFT
sets up or runs a project.

Project setup options
---------------------

Use ``--setup-only`` to create the project without launching Nextflow:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --manifest my_manifest.tsv \
      --setup-only

This writes the RAFT project directory, workflow files, loaded modules,
manifest, and parameter configuration, then stops before the Nextflow run. It
is useful when you want to inspect or edit the generated project before
execution.

``--setup-only`` is not a no-write dry run. RAFT does not currently provide a
mode that previews every setup action without creating or editing project
files.

Use ``--skip-downloads`` with off-the-shelf setup when you want to create the
project structure without downloading reference files or demonstration FASTQs:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --manifest my_manifest.tsv \
      --setup-only \
      --skip-downloads

This still initializes the project, fetches workflow configuration, and loads
workflow modules. Module loading can take a few minutes.

Use ``--workflow-profile`` to apply a prepared workflow configuration instead
of launching the config generator:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --manifest my_manifest.tsv \
      --workflow-profile standard

``standard`` means the default profile for that workflow/species/input
combination. Some workflows may provide additional profile names.

Use ``--edit-manifest`` to open the manifest generator even when you provide an
existing manifest:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --manifest my_manifest.tsv \
      --edit-manifest

Execution options
-----------------

Use ``--profile`` to pass a Nextflow runtime profile:

.. code-block:: console

  $ raft run --project-id my-project --profile slurm

Use ``--max-mem`` and ``--max-cpu`` to pass workflow-level resource caps:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --max-mem 256.GB \
      --max-cpu 32

These become Nextflow workflow parameters such as ``--max_mem`` and
``--max_cpu``.

Use ``--nf-params`` to pass additional parameters directly to Nextflow when
running an existing project:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --nf-params "--some_param value --another_param TRUE"

Use ``--no-resume`` to disable Nextflow resume behavior:

.. code-block:: console

  $ raft run --project-id my-project --no-resume

Output and report options
-------------------------

By default, RAFT removes the previous ``outputs/`` directory before running an
existing project. Use ``--keep-previous-outputs`` to leave existing outputs in
place:

.. code-block:: console

  $ raft run --project-id my-project --keep-previous-outputs

Use ``--no-reports`` to skip Nextflow report, trace, DAG, and timeline
generation:

.. code-block:: console

  $ raft run --project-id my-project --no-reports

Use ``--show-all-processes`` to show unfiltered Nextflow output. Without this
option, RAFT hides some noisy status and warning lines:

.. code-block:: console

  $ raft run --project-id my-project --show-all-processes

Workflow behavior options
-------------------------

By default, RAFT sets ``params.clean_intermediates`` to ``"TRUE"`` before
running when that parameter exists in the generated workflow. Use
``--keep-intermediates`` to leave that parameter unchanged:

.. code-block:: console

  $ raft run --project-id my-project --keep-intermediates

Use ``--include-all-samples`` to set every ``params.*include_all_samples``
assignment in ``workflow/main.nf`` to ``"TRUE"`` before running:

.. code-block:: console

  $ raft run --project-id my-project --include-all-samples

This is workflow-dependent. It only changes parameters that already exist in
the generated workflow.

Dataset and cloud options
-------------------------

Use ``--dataset`` instead of ``--manifest`` when running a supported
dataset-prep workflow:

.. code-block:: console

  $ raft run \
      --project-id hugolo-demo \
      --workflow lens \
      --version v1.9-dev \
      --dataset HugoLo_IPRES_2016

Use ``--cloud`` for advanced CLI cloud runs against bucket-backed paths:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --cloud gs://my-bucket/raft

For most cloud users, the BYOC launcher described in
:doc:`running-raft-on-the-cloud` is the preferred path.

Global options
--------------

Use ``--verbose`` or ``-V`` for more logging:

.. code-block:: console

  $ raft --verbose run --project-id my-project

Use ``--silent`` or ``-q`` to suppress informational output, including the
message of the day:

.. code-block:: console

  $ raft --silent run --project-id my-project

Use ``--bypass-dependencies`` only for advanced testing or constrained
environments where you intentionally want to skip dependency checks:

.. code-block:: console

  $ raft --bypass-dependencies run --project-id my-project