CLI Reference

The public release exposes a Python CLI named culsma.

Install

python -m pip install culsma

From a source checkout:

python -m pip install -e ".[dev]"

culsma run

Run one or more .culs source files through the pipeline.

culsma path/to/protocol.culs

The default output is a compact terminal summary of the protocol return.

culsma run path/to/protocol.culs --artifacts-dir tmp/run

Equivalent module form:

python -m culsma run \
  path/to/protocol.culs \
  --artifacts-dir tmp/run

If you want machine-readable JSON on stdout, use --json:

culsma run path/to/protocol.culs --json

If you want to save the machine-readable run output, use --output:

culsma run path/to/protocol.culs --output tmp/output.json

The saved payload uses culsma_run_output_v1: top-level returns contains protocol return values, while report contains the derived lab_report_v1 execution report.

Options:

Option	Meaning
positional path	Path to a .culs source file. Repeatable for multi-file merge.
--input	Backward-compatible path option for a .culs source file. Repeatable for multi-file merge.
--json	Print machine-readable run output JSON instead of terminal summary.
--output	Optional path for machine-readable run output JSON.
--artifacts-dir	Output directory for debug and intermediate JSON artifacts.
--fail-op	Stub driver failure injection by operation name. Repeatable.
--material-state-json	Optional initial material state JSON payload.
--inventory-check	Enable strict inventory validation and material checks.
--library-root	Optional directory containing importable library .culs modules. Repeatable.

culsma replay

Replay runtime state from a saved run artifact.

culsma replay --run-json tmp/run/run.json --out tmp/replayed_state.json

Options:

Option	Meaning
--run-json	Path to run.json.
--out	Output JSON path for reconstructed state.

Run Tests

From a source checkout:

python -m pytest -q