Command reference

scfoundry is one command with sub-commands. Task commands (download, check, embed, transfer, finetune, benchmark, geometry) launch Nextflow; the others (init, list, runs, info) never do.

usage: scfoundry [-h] [--version] <command> ...

  init       create a workspace (nextflow.config, data/, cache/, results/, runs/) and check the environment
  download   Download pretrained model checkpoints
  check      Check .h5ad files against the input contract (advisory report)
  embed      Zero-shot cell embeddings
  transfer   Label transfer with frozen embeddings (prototype / knn / logreg / mlp)
  finetune   Supervised fine-tuning (parameter updates) / prediction
  benchmark  Score embeddings (biological conservation, batch mixing)
  geometry   Representation-geometry probes of embeddings
  list       list methods or tasks
  runs       list recorded runs of the workspace
  info       show version, pipeline and workspace locations

scfoundry <command> --help prints the options of any command.

init

scfoundry init [--runtime {apptainer,singularity,docker}] [--gpu-id N] [--force] [--nextflow PATH] [directory]

Creates the workspace directories, writes nextflow.config from the bundled template with the chosen runtime enabled, writes the .scfoundry.json marker, and reports what it finds on the machine: Nextflow, the container runtime, nvidia-smi, Python. The directory defaults to the current one. --force rewrites nextflow.config in an existing workspace; --gpu-id seeds params.gpu_id.

Task commands

Task-specific options

Command	Options
download	--method (required); --model variant, e.g. Novae/novae-brain-0
check	--data (required: a file, a directory or a glob); --method for method-specific expectations; --label-key (default cell_type); --batch-key (default batch_id); --role {reference,query}
embed	--method, --data (required); --model; --batch-size; --batch-key (integration methods, default batch_id)
transfer	--method (required); --reference; --query; --fitted DIR; --classifier {prototype,knn,logreg,mlp} (default logreg); --label-key (default cell_type); --knn-k (default 15); --model; --batch-size
finetune	--method (required); --reference; --query; --fitted DIR; --label-key; --epochs; --batch-size (training); --model
benchmark	--embedding (required); --method label; --label-key; --batch-key; --metrics {bio,batch,all}; --clustering {leiden,kmeans}; --batch-max-cells
geometry	--embedding, --data (required); --method label; --label-key; --batch-key; --max-cells (default 20000); --seed (default 0)

Each is described on its task page: embed, transfer, finetune, benchmark, geometry, download, check.

Run options, shared by every task command

Option	Effect
--workspace DIR	Workspace to use. Default: $SCFOUNDRY_WORKSPACE, else the nearest parent of the current directory containing .scfoundry.json.
--outdir DIR	Root for published results (default <workspace>/results).
--run-name NAME	Name of the run directory under runs/<task>/ (default <timestamp>_<method>_<input>). Refuses to reuse an existing name.
--resume [RUN]	Resume the newest run with the same task, method and input — or the named run — with Nextflow’s -resume.
--gpu N	GPU index, or comma-separated list, exposed to the container (CUDA_VISIBLE_DEVICES under Apptainer, --gpus device=N under Docker).
--weights-dir DIR	Override params.model_weights_dir for this run.
--cache-dir DIR	Override params.cache_dir for this run.
--config FILE	Extra Nextflow configuration file, layered over the workspace nextflow.config (-c).
--profile NAME	Nextflow profile to activate (-profile), e.g. slurm.
--nextflow PATH	The Nextflow executable (default: $SCFOUNDRY_NEXTFLOW, else nextflow on PATH).
--dry-run	Print params.json and the Nextflow command; run nothing and create nothing.
--quiet	Less console output.

Forwarding pipeline parameters

Any --option a task command does not recognise is forwarded to Nextflow as a pipeline parameter, with a warning so that typos are visible:

scfoundry embed --method scfoundation --data cells.h5ad --scfoundation_pool_type max

[scfoundry] warning: forwarding unrecognised option(s) to Nextflow as parameters: --scfoundation_pool_type=max

Values are typed the way Nextflow would type them: 32 becomes an integer, true a boolean, null a null, anything else a string. A bare --flag is true. The parameters every method accepts are listed in the parameter reference.

Arguments after -- are passed verbatim to nextflow run, for Nextflow’s own options:

scfoundry embed --method scgpt --data cells.h5ad -- -with-report report.html -with-trace trace.txt

Exit status and output

A task command exits with Nextflow’s exit code. Its last lines name the run directory, which holds params.json, command.sh, run.json and nextflow.log:

[scfoundry] task=embed method=scgpt input=colon_1000
[scfoundry] workspace: /home/you/my_project
[scfoundry] run directory: runs/embed/20260828-162920_scgpt_colon_1000
[scfoundry] done (ok).

On failure the line reads warning: nextflow exited with code 1; see .../nextflow.log and the work directory of the failed task survives for inspection — see Troubleshooting.

list

scfoundry list methods                     # every method: id, name, category, gpu, tasks, container
scfoundry list methods --task finetune     # only methods supporting one task
scfoundry list tasks

method             name                 category     gpu  tasks                              container
c2s                C2S                  zero-shot    yes  download,embed,transfer            housy17/c2s:latest
cellama            CELLama              zero-shot    yes  download,embed,transfer,finetune   housy17/cellama:latest
...
pca                PCA                  reference    no   embed                              housy17/scllms:latest
harmony            Harmony              integration  no   embed                              satijalab/seurat:5.5.0

runs

scfoundry runs [--task TASK] [--limit N]

Lists the run directories of the workspace, newest first, from their run.json: start time, task, method, status, exit code and path.

info

scfoundry info

scfoundry  0.2.0
pipeline   /home/you/.conda/envs/nf-env/lib/python3.12/site-packages/scfoundry/pipeline
nextflow   25.10.0.5972 (/home/you/.conda/envs/nf-env/bin/nextflow)
workspace  /home/you/my_project
config     /home/you/my_project/nextflow.config

Environment variables

Variable	Effect
SCFOUNDRY_WORKSPACE	Default workspace when --workspace is not given. Also exported to Nextflow, where nextflow.config reads it to locate data/, cache/ and results/.
SCFOUNDRY_NEXTFLOW	The Nextflow executable to use.
SCFOUNDRY_PIPELINE	Pipeline directory to run instead of the bundled one. For developing the pipeline.
NXF_SYNTAX_PARSER	Set to v1 by scfoundry for every launch: the method modules use the classic DSL2 style that Nextflow ≥ 26 no longer parses by default.

Running Nextflow directly

scfoundry is a thin launcher around one Nextflow entry point, and there is nothing it can do that a direct call cannot — useful for CI, or for a pipeline developer:

export NXF_SYNTAX_PARSER=v1
export SCFOUNDRY_WORKSPACE=$PWD              # where data/, cache/ and results/ live
PIPELINE=$(scfoundry info | awk '/^pipeline/{print $2}')

nextflow run "$PIPELINE/main.nf" -c nextflow.config \
  --task embed --method scgpt --data cells.h5ad

--task selects the workflow; every other --parameter is as in the parameter reference. The entry points of the first release (embed_by_scfm.nf, fewshot_by_scfm.nf, finetune_by_scfm.nf, download_model_weights.nf) still run from a repository checkout but print a deprecation notice.