CLI Reference

The pipeline exposes a thin CLI through abacus.pipeline.runner.

Entry point

python -m abacus.pipeline.runner --config path/to/config.yml

AI advisor patch approval uses a separate file-based entry point:

python -m abacus.pipeline.approval \
  --approval-request results/<run>/08_ai_advisor/approval_request.yaml

On success, the CLI prints the final run directory:

Structured pipeline completed: results/my_run_20260308_153000_a8k2m7q1

Arguments

Flag Required Default Meaning
--config Yes None YAML config path
--output-dir No results Root directory for pipeline runs
--run-name No Config filename stem Optional run-name override
--dataset-path No None Combined dataset CSV override
--x-path No None Feature CSV override when not using --dataset-path
--y-path No None Target CSV override when not using --dataset-path
--holidays-path No None Holiday CSV override
--target-column No None Target column used when reading CSV input
--prior-samples No 20 Prior predictive samples for Stage 10
--draws No None Posterior draws override
--tune No None Posterior tuning steps override
--chains No None Posterior chains override
--cores No None Posterior cores override
--random-seed No 42 Shared random seed
--curve-samples No 100 Posterior samples for Stage 60 curves
--curve-points No 100 Number of x-values for saturation curves

Common command patterns

Use the dataset path from YAML

python -m abacus.pipeline.runner \
  --config data/demo/geo_panel/config.yml

Override the combined dataset path

python -m abacus.pipeline.runner \
  --config configs/geo_panel.yml \
  --dataset-path /data/geo_panel_latest.csv \
  --run-name geo_panel_latest

Use separate feature and target files

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --x-path /data/X.csv \
  --y-path /data/y.csv \
  --target-column revenue

Override sampler settings for one run

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --draws 1000 \
  --tune 1000 \
  --chains 4 \
  --cores 4 \
  --random-seed 42

Override the holiday CSV

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --holidays-path /data/holidays_uk_fr.csv

Approve an AI advisor patch

When ai_advisor.enabled: true and the advisor proposes a valid patch, Stage 08 writes 08_ai_advisor/approval_request.yaml with status: pending. Review the proposal, edit the request to status: approved, then run:

python -m abacus.pipeline.approval \
  --approval-request results/<run>/08_ai_advisor/approval_request.yaml \
  --approved-by "model owner"

The command writes approved_config.resolved.yaml and approval_record.yaml beside the advisor artifacts. It does not edit the source config.

How CLI overrides interact with YAML

The CLI does not replace the full YAML config. It only overrides the runtime fields exposed through PipelineRunConfig.

Important behaviours:

  • --dataset-path takes precedence over data.dataset_path.
  • --x-path and --y-path take precedence over data.x_path and data.y_path.
  • --holidays-path takes precedence over holidays.path.
  • --draws, --tune, --chains, --cores, and --random-seed are merged onto YAML fit.
  • --target-column affects CSV loading. Keep it consistent with target.column in YAML.

Exit behaviour

The CLI exits with status 0 on success. On failure, the process exits non-zero with the underlying exception.

The pipeline stops at the first stage failure. It does not provide flags to:

  • run only a subset of stages
  • continue after a failed stage
  • disable individual built-in stages other than omitting the optional optimization block from YAML

See Runner Overview and YAML Configuration for the execution model and config surface.