CLI Reference

The thesis CLI is built with Click. Source: src/thesis/cli.py. Run thesis --help for the auto-generated help text.

Top-level group

thesis [GLOBAL OPTIONS] <subcommand> [SUBCOMMAND OPTIONS]

Global options must appear before the subcommand.

Flag	Type	Default	Description
--log-level	DEBUG|INFO|WARNING|ERROR	INFO	Loguru log level for the file handler. Verbose mode (-v) raises this to DEBUG.
--log-dir <path>	path	logs	Directory for runtime log files.
-v, --verbose	flag	off	Verbose output: shows all events and underlying log records. Sets output.verbosity = "verbose" and bumps log level to DEBUG. Mutually exclusive with -q.
-q, --quiet	flag	off	Quiet output: errors and final result only. Sets output.verbosity = "quiet".
--summary	off|compact|full	compact	End-of-run summary detail. Overrides output.summary. full shows all bullets uncapped plus the per-result detail block (steps, files, commands, warnings) without needing -v.
--no-progress	flag	off	Disable spinners/progress bars. Auto-disabled for non-TTY or when CI/NO_COLOR is set. Overrides output.progress.
--version	flag	—	Print the version and exit.

thesis run

Execute a registered workflow for one or more patients.

thesis run -w <workflow> [-c <config>] [-p <patient>]... [OPTIONS]

Flag	Required	Default	Description
-w, --workflow	(or -s)	—	Registered workflow name. Run thesis list-workflows to list. Required unless -s/--script is given.
-s, --script <path>	(or -w)	—	Path to a user-supplied workflow script (.py) that registers a workflow via the @workflow decorator. Overrides --workflow.
-c, --config	no	default	Config name (e.g. default, mrtrix3, preprocess). Looked up under --config-dir.
-t, --protocol	no	(workflow default)	Protocol name override. Resolved as: CLI --protocol > config/patients/<id>.yaml protocol field > workflow default > error if none set.
-p, --patient-id	(or --all)	—	Patient ID. Repeat for multiple (-p P001 -p P002) and/or pass a comma-separated list (-p P001,P002). Mutually exclusive with --all.
--all	(or -p)	off	Discover and process all numeric patient folders in paths.inputs_dir.
-n, --pattern	no	—	Glob pattern for patient-folder discovery (requires --all). When omitted, only numeric folder names are discovered.
--parallel	no	off	Enable parallel execution via a Nipype meta-workflow. Implied by -j.
-j, --max-workers	no	—	Worker count. Overrides nipype.plugin_args.n_procs and implies --parallel.
-r, --retries	no	0	Retry attempts per patient on failure. Each retry waits 60 s; in parallel mode the meta-workflow is re-run with Nipype caching so only failed nodes re-execute.
--data-dir <path>	no	config.paths.assets_dir (else data)	Shared assets directory (templates, atlases, ROIs). When omitted it falls back to paths.assets_dir from the merged config. Carries the assets base only — it does not anchor input or output resolution (those are the independent --raw-data-dir/inputs_dir and --output-dir/output_dir roots).
--raw-data-dir <path>	no	(from config)	Override paths.inputs_dir for this run.
--output-dir <path>	no	outputs/<patient-id> (from config.paths.output_dir)	Override the workflow output directory.
--config-dir <path>	no	config	Configuration directory.
--graph	no	off	Write a workflow graph PNG to <output_dir>/workflow_graphs/.
--dry-run	no	off	Build the workflow (and run preflight verification) but don’t execute it.
--hemisphere	no	(from config)	left / right / both / both-separately. Overrides tractography.hemisphere.

Where inputs and outputs live

With the default config, paths resolve relative to the project root. The three location flags map to these defaults:

Flag	Default	Holds
--data-dir	data	Base directory anchoring discovery and input resolution.
--raw-data-dir	data/raw	Raw vendor inputs the preprocess/--all discovery scans, one folder per patient.
--output-dir	outputs/<patient-id>	Per-patient workflow outputs.

So for patient 114823, the default layout is:

data/raw/114823/        # raw vendor inputs (preprocess / --all discovery)
outputs/114823/         # workflow outputs

HCP-style workflows (hcp, mrtrix3, tract_synthseg) read pre-built inputs from the HCP-layout produced by preprocess (under data/processed/<patient_id>/T1w/, including T1w/Diffusion.bedpostX/); the hcp protocol sets paths.inputs_dir: processed/ so discovery points there. Override any of the three flags to relocate a tree without editing config.

Cohort-level workflows

atlas, learned_atlas, tract_similarity_cohort, tract_similarity_hcp_loo, and tract_similarity_sweep are cohort-level (their WorkflowEntry.is_cohort_level == True). They ignore -p/--patient-id and --all and scan the configured output directory for per-subject outputs.

Examples

# Single patient
thesis run -w hcp -p 114823 -c default
thesis run -w mrtrix3 -p 114823 -c mrtrix3

# Dry run (build, verify, but don't execute)
thesis run -w hcp -p 114823 -c default --dry-run

# Multiple patients, sequential, with retries
thesis run -w hcp -p 114823 -p 115320 -c default -r 2

# Auto-discover + parallel
thesis run -w hcp --all -c default -j 4
thesis run -w hcp --all --pattern 'P*' -c default

# End-to-end pipeline
thesis run -w full_pipeline -p 114823 -c full_pipeline
thesis run -w full_pipeline -p 114823 -c full_pipeline_mrtrix3  # MRtrix3 backend (tractography.method: mrtrix3)

# Cohort workflows (patient flags ignored)
thesis run -w atlas -c default
thesis run -w tract_similarity_cohort -c default
thesis run -w tract_similarity_sweep -c default

# Tractography hemisphere selection
thesis run -w hcp -p 114823 -c default --hemisphere both-separately

# Inspect workflow graph
thesis run -w hcp -p 114823 -c default --graph --dry-run

thesis list-workflows

List every registered workflow with description and (when set) default protocol. Auto-imports every thesis.workflows.* submodule to trigger self-registration.

thesis list-workflows [--config <name>] [--config-dir <path>]

Flag	Default	Description
-c, --config	default	Config to read paths.scripts_dir from (for discovering user scripts).
--config-dir	config	Configuration directory.

thesis list-configs

List available configuration files.

thesis list-configs [--config-dir <path>] [--subdir patients|protocols]

Flag	Default	Description
--config-dir	config	Configuration directory.
--subdir	—	Restrict listing to a subdirectory (patients, protocols, …).

thesis show-config

Print the merged configuration as YAML.

thesis show-config <config_name> [--config-dir <path>]

thesis show-config default

thesis info

Display version, Python/platform info, dependency status, and external-tool availability (FSL, ANTs).

thesis info

thesis stats collect

Re-run the post-batch tractography stats collector against an existing output directory and write the result as JSON. The schema matches what batch runs produce automatically under <output_dir>/batch_stats/.

thesis stats collect -o <output-dir> [OPTIONS]

Flag	Required	Default	Description
-o, --output-dir <path>	yes	—	Root directory containing per-subject output subdirectories.
-p, --patient <id>	no	(auto-discover)	Limit to specific patient IDs. Repeat for multiple.
--out <file>	no	<output-dir>/batch_stats/stats_<timestamp>.json	Destination JSON file.
--sd-threshold <float>	no	2.0	Outlier detection threshold in standard deviations.
--tractography-relpath <path>	no	tractography/probtrackx2	Relative path under each patient directory where the tractography run lives. Use tractography/mrtrix3 for the MRtrix3 backend.
--tract-similarity-subdir <path>	no	tract_similarity	Relative path under each patient directory where tract_similarity / tract_similarity_hcp_loo wrote metrics.json. Merged into that subject’s record under a tract_similarity key when present.

Examples

# Default (ProbTrackX2 layout)
thesis stats collect -o data/processed/

# MRtrix3 layout, custom output, looser outlier threshold
thesis stats collect \
  -o data/processed/ \
  --tractography-relpath tractography/mrtrix3 \
  --out reports/mrtrix3_stats.json \
  --sd-threshold 3.0

# Limit to specific subjects
thesis stats collect -o data/processed/ -p 114823 -p 115320

Exit codes

Code	Meaning
0	Run completed successfully (all patients succeeded, dry-run completed, or stats written).
1	One or more patients failed, were blocked (e.g. preflight verification failed), or stats collection found no subjects.
2	Click usage error (mutually exclusive flags, missing required arg).

CLI ↔ config mapping

CLI flag	YAML key	Notes
--hemisphere	tractography.hemisphere	left / right / both / both-separately
--raw-data-dir	paths.inputs_dir
-j / --max-workers	nipype.plugin_args.n_procs	Implies --parallel
-v / --verbose	output.verbosity = "verbose"	Also raises log level to DEBUG
-q / --quiet	output.verbosity = "quiet"
--summary	output.summary
--no-progress	output.progress = "off"
--log-level	(logger only)	DEBUG/INFO/WARNING/ERROR

See configuration/output.md for the YAML defaults that the CLI flags override.