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.

The report's material input and reagent-consumption tables come from material movements recorded during that run, not from replaying or summarizing the event log.

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 [INVENTORY_JSON]	Experimental post-run inventory reconciliation; it does not change runtime material behavior or provision missing material.
--library-root	Optional directory containing importable library .culs modules. Repeatable.

Select an Execution Provider

Culsma 1.0.9 adds --driver NAME to select an installed execution provider and --driver-config PATH to pass its configuration file.

The selected provider receives the complete program invocation, including input files, library roots and initial material state. Install and configure the provider before selecting its registered name. --driver-config requires --driver; omitting --driver keeps the standalone execution described above.

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