Which command should I use?
===========================

This page maps common tasks to the stable RAFT commands used throughout the
main documentation. If you already saw an error or unexpected result, see
:doc:`troubleshooting`.

Start or run a workflow
-----------------------

Create and run a new off-the-shelf project when you already have a manifest:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --species human \
      --input-data fastqs \
      --manifest my_manifest.tsv

Create the project but stop before launching Nextflow:

.. code-block:: console

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

Run or resume an existing project:

.. code-block:: console

  $ raft run --project-id my-project

Inspect a project
-----------------

Start with the read-only status command:

.. code-block:: console

  $ raft project-status --project-id my-project

Use JSON when another tool needs to consume the result:

.. code-block:: console

  $ raft project-status --project-id my-project --json

Validate or create a manifest
-----------------------------

Open the manifest generator by omitting ``--manifest`` during new project
setup, or use the browser-based manifest generator.

Create a command-line TSV starter:

.. code-block:: console

  $ raft manifest-template --output my_manifest.tsv

Validate a manifest:

.. code-block:: console

  $ raft check-manifest --manifest my_manifest.tsv

Review outputs
--------------

Open or generate report files:

.. code-block:: console

  $ raft generate-reports --project-id my-project

If the project status output reports failed Nextflow tasks, inspect:

- ``outputs/reports/trace-*.txt``
- ``logs/.nextflow.log``
- task work directories reported by Nextflow

Discover workflows
------------------

List workflow groups:

.. code-block:: console

  $ raft available-workflows

Inspect available species/input combinations:

.. code-block:: console

  $ raft available-workflows --workflow lens

Inspect one workflow input. By default this prints a compact summary with
profiles, steps, default parameter count, and the next command shapes. The
setup-only and run command examples omit ``--manifest`` because it is optional
for new projects; add ``--manifest <MANIFEST>`` when you already have one.

.. code-block:: console

  $ raft available-workflows --workflow lens --species human --input fastqs

Use ``--details`` when you need the full default parameter table:

.. code-block:: console

  $ raft available-workflows --workflow lens --species human --input fastqs --details

Use JSON for automation:

.. code-block:: console

  $ raft available-workflows --workflow lens --species human --input fastqs --json

The JSON form is compact by default. Add ``--details`` when automation needs
default parameter values.

Advanced module work
--------------------

Most users do not need these commands. They are useful when manually assembling
or debugging a workflow.

.. code-block:: console

  $ raft available-modules
  $ raft load-module --project-id my-project --module bwa
  $ raft list-steps --project-id my-project --module bwa
  $ raft add-step --project-id my-project --module bwa --step bwa_mem

Cluster usage
-------------

On a cluster or remote server:

- run RAFT from the RAFT workspace root, where ``.raft.cfg`` exists
- use ``raft manifest-template`` when the browser manifest generator is not
  convenient
- use ``--workflow-profile`` to avoid launching the config generator
- use ``--setup-only`` to create project files before submitting or reviewing a
  run