CLI Reference

Synopsis

cobre [--color <WHEN>] <SUBCOMMAND> [OPTIONS]

Global Options

Option	Type	Default	Description
--color <WHEN>	auto | always | never	auto	Control ANSI color output on stderr. auto colors only when stderr is a terminal; always forces color on — useful under mpiexec which pipes stderr through a non-TTY.

Subcommands

Subcommand	Synopsis	Description
init	cobre init [OPTIONS] [DIRECTORY]	Scaffold a new case directory from an embedded template
run	cobre run <CASE_DIR> [OPTIONS]	Load, train, simulate, and write results
validate	cobre validate <CASE_DIR>	Validate a case directory and print a diagnostic report
report	cobre report <RESULTS_DIR>	Query results from a completed run and print JSON to stdout
summary	cobre summary <OUTPUT_DIR>	Display the post-run summary from a completed output directory
schema	cobre schema <COMMAND>	Manage JSON Schema files for case directory input types
version	cobre version	Print version, solver backend, and build information

---

cobre init

Scaffolds a new case directory from an embedded template. Creates all required input files (config.json, penalties.json, stages.json, system files, etc.) so a new user can start from a working example.

Arguments

Argument	Type	Description
[DIRECTORY]	Path	Target directory where template files will be written

Options

Option	Type	Default	Description
--template <NAME>	string	—	Template name to scaffold (e.g., 1dtoy)
--list	flag	off	List all available templates and exit
--force	flag	off	Overwrite existing files in the target directory

Examples

# List available templates
cobre init --list

# Scaffold the 1dtoy example in a new directory
cobre init --template 1dtoy my_study

# Overwrite files in an existing directory
cobre init --template 1dtoy --force my_study

---

cobre run

Executes the full solve lifecycle for a case directory:

1. Load — reads all input files and runs the layered validation pipeline
2. Train — trains an SDDP policy using the configured stopping rules
3. Simulate — (optional) evaluates the trained policy over simulation scenarios
4. Write — writes all output files to the results directory

Whether simulation runs is controlled by simulation.enabled in config.json. Stochastic artifact export is controlled by exports.stochastic in config.json.

Arguments

Argument	Type	Description
<CASE_DIR>	Path	Path to the case directory containing input data files and config.json

Options

Option	Type	Default	Description
--output <DIR>	Path	<CASE_DIR>/output/	Output directory for results
--threads <N>	integer	1	Number of worker threads per MPI rank. Each thread solves its own LP instances; scenarios are distributed across threads.
--comm-backend <WHICH>	auto | local | mpi	auto	Communication backend. auto selects the MPI backend when the process is launched under an MPI launcher (mpiexec/mpirun/srun) and the local backend otherwise; local forces a single process; mpi forces the MPI backend and fails with a clear message on a binary built without MPI support.
--quiet	flag	off	Suppress the banner and progress bars. Errors still go to stderr

Config-First Principle

The CLI follows a config-first design: config.json defines what to compute, CLI flags define how to run it. A study is fully specified by its case directory — the same case produces the same results regardless of which CLI flags are used.

Concern	Controlled by
Simulation on/off	simulation.enabled in config.json
Stochastic export on/off	exports.stochastic in config.json
Forward passes, iterations	training.* in config.json
Cut selection	training.cut_selection in config.json
Inflow method	modeling.inflow_non_negativity in config.json

Examples

# Run a study with default output location
cobre run /data/cases/hydro_study

# Write results to a custom directory
cobre run /data/cases/hydro_study --output /data/results/run_001

# Use 4 worker threads per MPI rank
cobre run /data/cases/hydro_study --threads 4

# Run without any terminal decorations (useful in scripts)
cobre run /data/cases/hydro_study --quiet

# Force color output when running under mpiexec
cobre --color always run /data/cases/hydro_study

# Run with MPI across 4 ranks
mpiexec -np 4 cobre run /data/cases/hydro_study

Output format

cobre run prints this summary to stderr once the study finishes. It carries the same convergence, policy-rows, and LP-solve lines as the cobre summary reconstruction, plus a live-run-only Time split block that decomposes the total training wall time into Forward / Backward / Serial phases (see the arithmetic notes below).

Training complete in 4m 12s (42 iterations, converged at iter 38)
  Lower bound:  4.85000e4 $/stage
  Upper bound:  4.90000e4 +/- 2.50000e2 $/stage
  Gap:          1.0%
  Policy rows:  980000 active / 1250000 generated
  LP solves:    84000 (81900 first-try, 2000 retried, 100 failed)
  Avg iter:     6000ms
  Time split:   Forward  2m 51s (68%)   solve 2m 40s · wait 14.0s (8% of phase)
                Backward 1m 9s (27%)   solve 58.0s · wait 7.0s (10% of phase)
                Serial   12.0s (5%)   bound 4.0s · selection 2.0s · allreduce 1.0s · sync 500ms · other 4.5s

The three walls in the Time split block sum to the total training time (Serial = total − Forward − Backward, clamped at zero). For Forward/ Backward, solve is the per-worker mean LP-solve wall time for that phase (cumulative solve time across all workers divided by parallelism, capped at the phase wall); wait is that phase’s worker wait from load imbalance, shown as a percentage of the phase wall. In the Serial line, bound is lower-bound evaluation time and selection is row-selection time; allreduce (MPI forward-bound synchronization) and sync (per-stage row-sync allgatherv) appear only on MPI runs, inserted only when nonzero; other absorbs rayon scheduling overhead plus any unaccounted residual. The whole Time split block is omitted when per-iteration phase-wall timing is unavailable — see cobre summary below.

SLURM clusters

Launching Cobre under SLURM (srun/sbatch), the hybrid MPI + threads mapping, the key SLURM flags, and PMI selection are covered in full on the HPC & Cluster Deployment page, alongside how to obtain or build the MPI-enabled binary and a worked AWS ParallelCluster reference architecture.

---

cobre validate

Runs the layered validation pipeline and prints a diagnostic report to stdout.

On success, prints entity counts:

Valid case: 3 buses, 12 hydros, 8 thermals, 4 lines
  buses: 3
  hydros: 12
  thermals: 8
  lines: 4

On failure, prints each error prefixed with error: and exits with code 1.

Arguments

Argument	Type	Description
<CASE_DIR>	Path	Path to the case directory to validate

Options

None.

Examples

# Validate a case directory before running
cobre validate /data/cases/hydro_study

# Use in a script: only proceed if validation passes
cobre validate /data/cases/hydro_study && cobre run /data/cases/hydro_study

---

cobre report

Reads the JSON manifests written by cobre run and prints a JSON summary to stdout.

The output has the following top-level shape:

{
  "output_directory": "/abs/path/to/results",
  "status": "complete",
  "bounds": { "final_lower_bound": ..., "final_upper_bound": ... },
  "training": { "iterations": {}, "convergence": {}, "row_pool": {}, "bounds": {}, "configuration": {}, "problem_dimensions": {} },
  "cost": { "mean_cost": ..., "std_cost": ... } | null,
  "simulation": { "scenarios": {}, "cost": {} } | null
}

cost and simulation are null when the corresponding files are absent (e.g., when simulation was disabled in config.json).

Arguments

Argument	Type	Description
<RESULTS_DIR>	Path	Path to the results directory produced by cobre run

Options

None.

Examples

# Print the full report to the terminal
cobre report /data/cases/hydro_study/output

# Extract the convergence gap using jq
cobre report /data/cases/hydro_study/output | jq '.training.convergence.final_gap_percent'

# Check the run status in a script
status=$(cobre report /data/cases/hydro_study/output | jq -r '.status')
if [ "$status" = "complete" ]; then
  echo "Training converged"
fi

---

cobre summary

Reads the training manifest and convergence log from a completed run’s output directory and prints the same human-readable summary table that cobre run displays at the end of a study. This lets users inspect a past run without re-executing it.

All output goes to stderr, matching the cobre run convention. stdout is reserved for machine-readable output (see cobre report).

File resolution

File	Required	Behaviour when absent
training/metadata.json	Yes	Exits with code 2 (I/O error)
training/convergence.parquet	No	Falls back to zero-valued timing fields; gap comes from metadata.json
simulation/metadata.json	No	Simulation section is omitted from the output

Output format

Training complete in 3m 42s (42 iterations, converged at iter 38)
  Lower bound:  4.85000e4 $/stage
  Upper bound:  4.90000e4 +/- 2.50000e2 $/stage
  Gap:          1.0%
  Policy rows:  980000 active / 1250000 generated
  LP solves:    84000
  Avg iter:     5286ms

Simulation complete in 0.0s (200 scenarios)
  Completed: 198  Failed: 2

cobre summary reconstructs this summary from persisted files (training/metadata.json and training/convergence.parquet) and therefore omits the Time split block — per-iteration phase timing is not written to metadata.json. See cobre run’s Output format section above for the block a live run prints.

The simulation section is omitted when simulation/metadata.json is absent (e.g., when simulation was disabled in config.json).

Arguments

Argument	Type	Description
<OUTPUT_DIR>	Path	Path to the output directory produced by cobre run

Options

None.

Examples

# Print the summary for a completed run
cobre summary /data/cases/hydro_study/output

# Inspect a run that used a custom output directory
cobre summary /data/results/run_001

---

cobre schema

Manages JSON Schema files for case directory input types. Currently supports exporting schemas.

Subcommands

Subcommand	Synopsis	Description
export	cobre schema export [--output-dir <DIR>]	Export JSON Schema files for all input types

Option	Type	Default	Description
--output-dir <DIR>	Path	.	Directory to write schema files into. Created if absent. Existing schemas are overwritten.

Examples

# Export schemas to the current directory
cobre schema export

# Export schemas to a specific directory
cobre schema export --output-dir /data/schemas

---

cobre version

Prints the binary version, active solver and communication backends, compression support, host architecture, and build profile.

Output Format

cobre   v0.10.0
solver: HiGHS
comm:   local
zstd:   enabled
arch:   x86_64-linux
build:  release (lto=thin)

Line	Description
cobre v{version}	Binary version from Cargo.toml
solver: HiGHS	Active LP solver backend (HiGHS in all standard builds)
comm: local or comm: mpi	Communication backend (mpi only when compiled with the mpi feature)
zstd: enabled	Output compression support
arch: {arch}-{os}	Host CPU architecture and operating system
build: release or build: debug	Cargo build profile

Arguments

None.

Options

None.

---

Exit Codes

All subcommands follow the same exit code convention.

Code	Category	Cause
0	Success	The command completed without errors
1	Validation	Case directory failed the validation pipeline — schema errors, cross-reference errors, semantic constraint violations, or policy compatibility mismatches
2	I/O	File not found, permission denied, disk full, or write failure during loading or output
3	Solver	LP infeasible subproblem or numerical solver failure during training or simulation
4	Internal	Communication failure, unexpected channel closure, or other software/environment problem

Codes 1–2 indicate user-correctable input problems; codes 3–4 indicate case/environment problems. Error messages are printed to stderr with error: prefix and hint lines. See Error Codes for a detailed catalog.

---

Environment Variables

Cobre reads no configuration from environment variables. Every setting comes from the case’s config/data files and from cobre CLI arguments — thread count from --threads, color from --color, and the communication backend from --comm-backend. Terminal width (for progress rendering under a piped stderr) and the hostname recorded in run provenance are queried directly from the terminal and the OS. The one environment signal cobre still consults is whether it was launched under an MPI launcher, used only by --comm-backend auto to select a backend — a runtime fact, not a configuration channel.