Project status

raft project-status is a read-only command for summarizing the current state of one RAFT project.

It does not repair, download, delete, rerun, or modify project files. It is safe to run repeatedly while inspecting a project.

Basic usage

Run:

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

The command reports:

  • project path and detected workflow context

  • an overall status label such as setup complete, not run yet, run failed, or complete, reports available

  • the manifest RAFT believes the project is using

  • manifest row, patient, dataset, run, sample-prefix, Group, and Alleles summaries

  • latest Nextflow trace status counts and failed task count

  • presence of outputs/, outputs/samples/, outputs/qc/, and outputs/reports/

  • simple output file counts

  • workflow-specific checks when RAFT recognizes the workflow

  • a Next section with suggested follow-up commands

Use JSON for automation:

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

Next actions

The Next section is intended to answer “what should I do now?” without changing project files. The suggestions are derived from detected project state.

After --setup-only, project-status suggests starting the workflow:

Status: setup complete, not run yet

Next:
  Start the workflow:
    raft run --project-id my-project
  Open the viewer without preloaded outputs:
    raft generate-reports --project-id my-project --no-load

After a failed run, it points to the latest trace, the Nextflow log, and the rerun command:

Status: run failed

Next:
  Inspect the latest trace:
    less /path/to/projects/my-project/outputs/reports/trace-20260419.txt
  Inspect the Nextflow log:
    less /path/to/projects/my-project/logs/.nextflow.log
  After fixing the problem, rerun:
    raft run --project-id my-project

When reportable outputs are present, it suggests opening the report viewer and packaging the project:

Status: complete, reports available

Next:
  Open the report viewer:
    raft generate-reports --project-id my-project
  Package the project:
    raft package-project --project-id my-project

Manifest detection

A project can contain multiple files under inputs/metadata. project-status therefore does not assume that the newest or only manifest-like file is the one used by the workflow.

Detection order is:

  1. Read workflow/main.nf.

  2. Look for manifest-like Channel.fromPath(...) entries.

  3. Resolve ${params.*} expressions using parameter assignments in main.nf. For example, RAFT resolves ${params.metadata_dir}/my.manifest.tsv using the project’s actual inputs/metadata directory.

  4. If exactly one referenced manifest exists, report that file as the manifest source.

  5. If main.nf is ambiguous, fall back to files under the project’s inputs/metadata directory.

The output includes the manifest source, for example:

Manifest: inputs/metadata/lens.human.demo.manifest
Manifest source: workflow/main.nf

If multiple manifest-like files exist and main.nf does not identify one unambiguously, project-status reports a warning.

Workflow-specific status

project-status is designed so workflow-specific checks can be added without changing the user-facing command. Workflow-owned status files use the same repository pattern as manifest and report UI templates.

RAFT looks for status configs in this order:

  1. project-local workflow config checkouts, such as <project>/lens-human-fastqs/lens.human.fastqs.status.json

  2. packaged RAFT defaults under src/raft/ui/static/workflows/<workflow>/

The most specific filename is preferred:

<workflow>.<species>.<input>.status.json
<workflow>.<species>.status.json
<workflow>.status.json
status.json

This means a workflow config repository such as lens-human-fastqs can own lens.human.fastqs.status.json beside:

lens.human.fastqs.config
lens.human.fastqs.json
lens.human.fastqs.manifest-ui.json
lens.human.fastqs.report-ui.json

Status config files can define:

  • expected output paths

  • table/report glob patterns

  • fields to count

  • required columns

  • columns that should warn when blank in every row

For LENS projects, it reports:

  • number of final LENS report files

  • row count for the first final report

  • candidate counts by antigen_source

  • warnings for missing configured required columns, such as candidate_id and review columns

  • warnings for final-report columns that are blank in all rows for selected tumor-level fields

Interpreting warnings

Warnings are meant to identify conditions that deserve review. They are not always fatal errors.

Examples:

  • latest trace contains failed tasks

  • multiple manifest-like files were found but main.nf did not identify one

  • final LENS report lacks candidate_id

  • review columns are missing from the final LENS report

Use these warnings to decide whether to inspect logs, trace files, intermediate outputs, or workflow-specific documentation before trusting the final report.