CLI Reference

Synopsis

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

Global Options

Subcommands

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

Options

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

Options

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.

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

SLURM clusters

On SLURM-managed clusters, launch Cobre with srun instead of mpiexec. SLURM handles process placement, CPU binding, and NUMA-aware memory allocation automatically.

Basic launch:

srun --mpi=pmi2 -n 4 ./cobre-mpi run /data/cases/hydro_study

Hybrid MPI + threads (recommended for production):

Cobre uses MPI for inter-node communication and rayon threads for intra-node parallel LP solves. Set --cpus-per-task to control the thread count per rank:

#!/bin/bash
#SBATCH --job-name=cobre
#SBATCH --nodes=4
#SBATCH --ntasks-per-node=2
#SBATCH --cpus-per-task=16
#SBATCH --mem-bind=local
#SBATCH --output=cobre_%j.log

# Pin each rank to its allocated cores; use NUMA-local memory.
srun --cpu-bind=cores --mpi=pmi2 ./cobre-mpi run /data/case \
    --threads "$SLURM_CPUS_PER_TASK"

Key SLURM flags for Cobre:

Tip: On modern SLURM clusters (22.05+), --mpi=pmix is preferred over --mpi=pmi2 for better scalability. Check your cluster’s default with srun --mpi=list.

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

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

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

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%
  Cuts:         980000 active / 1250000 generated
  LP solves:    84000

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

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

Arguments

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

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.9.1
solver: HiGHS
comm:   local
zstd:   enabled
arch:   x86_64-linux
build:  release (lto=thin)

Arguments

None.

Options

None.

Exit Codes

All subcommands follow the same exit code convention.

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