CLI Usage

Purpose

Define the supported command-line interface for scripts/dsambayes.R, including required flags, optional flags, and execution semantics.

Prerequisites

Before using the CLI:

  • Complete Install and Setup.
  • Run commands from repository root.
  • Ensure DSAMbayes is installed in the role-specific R_LIBS_USER selected by dsambayes_set_r_library host.

Entry point

Rscript scripts/dsambayes.R <command> [flags]

Operational commands construct the package-owned DSAMbayes::runner_cli_adapter() before reading configs, fitting models, or writing artefacts. The startup panel records both the loaded package version and the checkout version from DESCRIPTION. runme.R applies the same gate and records the versions as package_version and checkout_version.

The versions must match exactly. A mismatch exits with status 2 before runner work begins. Reinstall the current checkout into the active role-specific library, then retry:

source scripts/r-library-path.sh
dsambayes_set_r_library host
R -q -e 'remotes::install_local(".", dependencies = NA, upgrade = "never")'
R -q -e 'library(DSAMbayes); packageVersion("DSAMbayes")'

This gate proves declared-version equality. It cannot prove Git-revision equality when the installed package has no revision metadata. Reinstall after changing branches or pulling changes that keep the same package version. For a CLI run, session_info.txt records the commit of the checkout that supplied the entry-point script. This identifies the checkout; it does not independently prove that a locally installed package with the same version contains identical source bytes.

The script supports these commands:

  • init
  • validate
  • run
  • help (or -h / --help)

Command summary

Command Required flags Optional flags Behaviour
init --out --template, --overwrite Writes a config template file.
validate --config --run-dir Runs config and data checks only (dry_run = TRUE).
run --config --run-dir Executes the full pipeline (dry_run = FALSE) and writes run artefacts.
help none none Prints usage text and exits.

Flag reference

init

  • --out <path> (required): output path for the generated YAML file.
  • --template <name> (optional): template name. Default is blm.
    • Supported values in script: master, blm, re, cre, pooled, hierarchical.
    • hierarchical maps to the same template file as re.
  • --overwrite (optional flag): allow overwrite of an existing --out file.

validate

  • --config <path> (required): YAML config path.
  • --run-dir <path> (optional): explicit run directory path.

run

  • --config <path> (required): YAML config path.
  • --run-dir <path> (optional): explicit run directory path.

Usage examples

Show help

Rscript scripts/dsambayes.R --help

Expected outcome: usage panel is printed with command syntax and notes.

Create a new config from template

Rscript scripts/dsambayes.R init --template blm --out config/local_quickstart.yaml

Expected outcome: config/local_quickstart.yaml is created.

Validate only (dry-run behaviour)

Rscript scripts/dsambayes.R validate --config config/blm_timeseries.yaml

Expected outcome: validation completes without fitting Stan models.

Validate with explicit run directory

Rscript scripts/dsambayes.R validate \
    --config config/blm_timeseries.yaml \
    --run-dir results/quickstart_validate

Expected outcome: validation uses the provided run directory path when writing run metadata.

Execute full run

Rscript scripts/dsambayes.R run --config config/cre_geo_panel.yaml

Expected outcome: full modelling pipeline executes and artefacts are written under results/.

Execute full run with explicit run directory

Rscript scripts/dsambayes.R run \
    --config config/cre_geo_panel.yaml \
    --run-dir results/quickstart_run

Expected outcome: artefacts are written to results/quickstart_run (subject to overwrite rules in config).

Exit and error behaviour

  • Exit 0: command completed successfully. For run, this means the pipeline completed and diagnostics did not end in overall_status: fail.
  • Exit 1: run completed far enough to preserve the fitted result, but the outcome is non-publishable. This includes diagnostics overall_status: fail, requested scenario-analysis failures, diagnostics publish-gate failures, and post-fit artefact-write failures.
  • Exit 2: CLI argument, config, or runtime error before a completed run result could be returned.
  • Typical hard failures include:
    • DSAMbayes not installed.
    • Loaded DSAMbayes and checkout versions do not match.
    • Missing required flags (--out or --config).
    • Unknown command.
    • Unknown argument format.

Operational notes

  • validate is the recommended pre-run gate. Use it before run whenever you change config or data.
  • run prints a run summary and suggested next-step artefacts at completion.
  • The CLI itself does not define model semantics. Its package adapter delegates execution to DSAMbayes::run_from_yaml().