Command Line Interface

multiversum provides a command-line interface (CLI) to run multiverse analyses directly from your terminal. After installing the package, you can run the CLI either via python -m multiversum or uv run -m multiversum (if using uv).

python -m multiversum

Run a multiverse analysis from the command line.

Usage:

python -m multiversum [OPTIONS]

Options:

  --mode [full|continue|test|partial-parallel|finalize]
                                  How to run the multiverse
                                  analysis.(continue: continue from previous
                                  run, full: run all universes, test: run a
                                  minimal set of universes where each unique
                                  option appears at least once, partial-
                                  parallel: run a partial range of universes
                                  in parallel see --partialfinalize: finalize
                                  the previous run e.g. after running in
                                  partial-parallel mode)
  --config PATH                   Relative path to a TOML, JSON or Python file
                                  with a config for the multiverse. Defaults
                                  to searching for multiverse.toml,
                                  multiverse.json, multiverse.py (in that
                                  order).
  --universe PATH                 Relative path to the universe file to run.
                                  Defaults to searching for universe.ipynb,
                                  universe.py (in that order).
  --output-dir PATH               Relative path to output directory for the
                                  results.
  --seed INTEGER                  The seed to use for the analysis (Defaults
                                  to 80539).
  --u-id TEXT                     Examine only a single universe with the
                                  given universe id (or starting with the
                                  provided id).
  --grid-only                     Only export the multiverse grid without
                                  running the analysis.
  --grid-format [json|csv|none]   Format of the exported multiverse grid
                                  (json, csv, or none to skip export).
  --n-jobs, --njobs INTEGER       Number of CPUs to use for parallel
                                  processing. -1 uses all CPUs, -2 uses all
                                  but one CPU (default), and 1 disables
                                  parallel processing.
  --partial TEXT                  Run only a specific percentage range of
                                  universes. Format: 'start%,end%' (e.g.
                                  '0%,50%' or '0,20%'). Set mode to 'partial-
                                  parallel' to run in parallel and avoid race
                                  conditions.
  --retry-errors                  When mode=continue, retry universes that
                                  previously resulted in errors.
  --retry-error-type TEXT         When mode=continue, retry only universes
                                  that failed with this specific error type.
  --help                          Show this message and exit.