Managing RAFT projects
======================

Most users interact with RAFT projects through ``raft run`` and
``raft generate-reports``. The commands below are useful once you have several
projects, need to move a project between environments, or need to preserve a
project snapshot.

Generated project README
------------------------

RAFT writes a ``README.md`` into each created project directory. It records the
project id, detected workflow context, manifest path, creation command, common
follow-up commands, and important output/log paths.

Open this file when returning to an older project or when sharing a project
directory with another user.

Check project status
--------------------

Use ``raft project-status`` to inspect a project without changing it:

.. code-block:: console

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

The status command summarizes the detected workflow, the manifest referenced by
``workflow/main.nf``, manifest sample counts, latest trace status, output
directories, and workflow-specific checks when available.

For more detail, see :doc:`project-status`.

Package a project
-----------------

Use ``raft package-project`` to create a portable project snapshot:

.. code-block:: console

  $ raft package-project --project-id my-project

By default, RAFT writes:

.. code-block:: text

  projects/my-project/rftpkgs/default.rftpkg

Choose a package name with ``--output``:

.. code-block:: console

  $ raft package-project \
      --project-id my-project \
      --output my-project-2026-04-14

This writes ``my-project-2026-04-14.rftpkg`` under the project's
``rftpkgs/`` directory.

Useful options:

- ``--no-git`` excludes Git metadata from packaged workflow module
  directories
- ``--no-checksums`` skips checksum generation

For the package file structure, see :doc:`rftpkg`.

Load a packaged project
-----------------------

Use ``raft load-project`` to create a project from an existing ``.rftpkg``:

.. code-block:: console

  $ raft load-project \
      --project-id restored-project \
      --rftpkg /path/to/default.rftpkg

RAFT initializes a new project directory, extracts the package into the
project's internal ``.raft/`` area, restores the packaged ``inputs/`` and
``workflow/`` directories, and rewrites stored project identifiers where
needed.

You can also load from a Git repository that stores project packages:

.. code-block:: console

  $ raft load-project \
      --project-id restored-project \
      --repo-url https://example.org/group/project-packages.git \
      --branch main

Push a package to a repository
------------------------------

``raft push-project`` is intended to push an existing package into a project
package repository:

.. code-block:: console

  $ raft push-project \
      --project-id my-project \
      --rftpkg default

.. warning::

   This command exists in RAFT but is less polished than the standard
   off-the-shelf run path. Validate repository configuration and package
   contents before relying on it for production transfer.

Rename a project
----------------

Use ``raft rename-project`` to rename a project and update selected internal
files:

.. code-block:: console

  $ raft rename-project \
      --project-id old-project-id \
      --new-id new-project-id

RAFT updates known project-id references in:

- ``workflow/mounts.config``
- ``workflow/nextflow.config``
- ``.raft/auto.raft``

Then it moves the project directory to the new project id.

.. warning::

   Rename support is limited to the files RAFT explicitly rewrites. If you
   manually added project-id references elsewhere, review the project after
   renaming.