CLI reference

meridian-tools provides a command-line interface with two subcommands: run and demo.

Global usage

meridian-tools <subcommand> [options]

`meridian-tools run`

Execute a meridian-tools pipeline run from an authored YAML config.

meridian-tools run --config <path> [--output-dir <dir>] [--run-name <name>] [--traceback]

Arguments

Argument	Required	Default	Description
`--config`	Yes	—	Path to the meridian-tools YAML configuration file.
`--output-dir`	No	`runs`	Directory where dated run folders will be created.
`--run-name`	No	`project.name` from YAML	Optional run name override.
`--traceback`	No	`false`	Show the full Python traceback on failure.

Examples

# Basic run
meridian-tools run --config project.yml

# Custom output directory
meridian-tools run --config project.yml --output-dir output/model_runs

# Named run with traceback on failure
meridian-tools run --config project.yml --run-name client-q1-review --traceback

Exit codes

Code	Meaning
`0`	Pipeline completed successfully.
`1`	Pipeline failed. Error details are printed to stderr. Use `--traceback` for the full stack trace.

Failure reporting

The CLI distinguishes five broad failure classes:

config loading or Pydantic validation failures before wrapper preflight
dependency preflight failures before run-directory creation
validation-execution contract failures before run-directory creation
wrapper-owned ConfigPreflightError failures before run-directory creation
PipelineRunFailure after the dated run directory already exists

Dependency preflight covers google-meridian[schema] support and optional plot-export support. Validation-execution contract failures cover incompatible single-run validation requests such as direct rolling_origin execution. Wrapper preflight covers only the closed config/data matrix documented in the configuration guide.

For PipelineRunFailure, the CLI prints the concrete failed run directory, manifest path, and stage name when available so the partial run can be inspected immediately. --traceback still shows the original underlying exception because it is preserved through __cause__.

Validation strategy restrictions

The CLI executes a single pipeline run. Configs with validation.strategy: rolling_origin cannot be run directly from the CLI because they require multiple sequential runs. Use the Python API for rolling-origin workflows.

Configs with strategy: none or strategy: blocked_tail work directly from the CLI.

`meridian-tools demo`

Run one of the bundled reference demos or list available demos.

meridian-tools demo [<name>] [--list] [--output-dir <dir>] [--run-name <name>] [--traceback]

Arguments

Argument	Required	Default	Description
`<name>`	Yes (unless `--list`)	—	Bundled demo name to execute. One of: `timeseries`, `geo_panel`.
`--list`	No	`false`	List supported demos and exit. Cannot combine with a demo name.
`--output-dir`	No	`runs/demos/` (source checkout) or `./runs/demos/` (installed)	Override the output root directory.
`--run-name`	No	None (uses `project.name` from the demo config)	Optional run name override.
`--traceback`	No	`false`	Show the full Python traceback on failure.

Examples

# List available demos
meridian-tools demo --list

# Run the timeseries demo
meridian-tools demo timeseries

# Run with a custom output directory
meridian-tools demo geo_panel --output-dir sandbox/demo-output

# Run with a custom name
meridian-tools demo timeseries --run-name demo-review-q2

Available demos

Name	Description
`timeseries`	National timeseries demo using bundled reference data.
`geo_panel`	Geo-panel demo using bundled reference data.

Both demos exercise the full staged pipeline including response curves and optimisation.

Lightweight import

The CLI is designed for fast startup. Running meridian-tools --help or meridian-tools demo --list does not import TensorFlow, NumPy, Meridian, or ArviZ. Heavy imports are deferred until pipeline execution begins.

Entrypoints

The primary CLI entrypoint is the console script registered in pyproject.toml:

[project.scripts]
meridian-tools = "meridian_tools.cli:main"

The supported module-path equivalent is:

python -m meridian_tools.cli run --config project.yml

The package-level form below is not part of the supported contract in this milestone:

python -m meridian_tools run --config project.yml

Source-tree wrapper

When working from the source checkout, runme.py provides equivalent functionality:

python runme.py run --config project.yml --output-dir runs
python runme.py demo timeseries
python runme.py demo --list

See the demo guide for more details on the runme.py wrapper.