# CLI Reference

LifeGrid includes a headless CLI for running simulations without a GUI. It is useful for scripting, batch processing, and CI pipelines.

## Usage

```bash
python src/cli.py [OPTIONS]
```

## Options

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--mode` | `-m` | string | `conway` | Automaton mode (see aliases below) |
| `--rule` | | string | | Custom B/S rule string (e.g., `B36/S23`). Overrides `--mode`. |
| `--width` | `-W` | int | 100 | Grid width |
| `--height` | `-H` | int | 100 | Grid height |
| `--steps` | `-n` | int | 100 | Number of generations to simulate |
| `--pattern` | `-p` | string | `Random Soup` | Initial pattern name to load |
| `--cell-size` | | int | 4 | Cell size in pixels (for image/video export) |
| `--export` | `-o` | path | | Export file path. Format determined by extension. |
| `--fps` | | int | 10 | Frames per second (GIF, MP4, WebM) |
| `--snapshot-every` | | int | 1 | Collect a frame for animation export every N generations |
| `--quiet` | `-q` | flag | | Suppress progress output |

## Mode Aliases

| Alias | Automaton |
|-------|-----------|
| `conway` | Conway's Game of Life |
| `highlife` | HighLife |
| `immigration` | Immigration |
| `rainbow` | Rainbow |
| `wireworld` | Wireworld |
| `briansbrain` | Brian's Brain |
| `ant` | Langton's Ant |
| `generations` | Generations |
| `hexagonal` | Hexagonal Life |

## Export Formats

The `--export` flag determines the output format by file extension:

| Extension | Output |
|-----------|--------|
| `.png` | Single PNG snapshot of the final grid |
| `.gif` | Animated GIF built from collected frames |
| `.mp4` | MP4 video built from collected frames |
| `.webm` | WebM video built from collected frames |
| `.csv` | CSV with per-generation statistics — columns: `generation`, `population`, `density` |
| `.json` | JSON with mode, dimensions, step count, final population, and full grid |

## Examples

### Basic simulation

```bash
python src/cli.py --mode conway --steps 500
```

### Export an animated GIF

```bash
python src/cli.py --mode highlife --steps 1000 --export output/highlife.gif --fps 20
```

### Custom rule with video export

```bash
python src/cli.py --rule B36/S23 --steps 2000 -W 128 -H 128 --export output/custom.mp4 --fps 30
```

### CSV statistics

```bash
python src/cli.py --mode briansbrain --steps 500 --export output/stats.csv --quiet
```

The CSV file contains one row per generation with columns:
`generation`, `population`, `density`

> **Note:** The richer per-generation metrics (`live`, `delta`, `entropy`, `complexity`) are produced by the GUI's `SimulationState.export_metrics_csv()` export, not the CLI.

### Sparse GIF (collect every 10th frame)

```bash
python src/cli.py --mode wireworld --steps 1000 --snapshot-every 10 --export output/wireworld.gif
```

With `--snapshot-every 10`, one frame is collected every 10 generations, producing a 100-frame GIF instead of a 1000-frame one.

### Silent batch run

```bash
for mode in conway highlife briansbrain; do
    python src/cli.py --mode $mode --steps 500 --export output/${mode}.gif --quiet
done
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Invalid arguments or export failure |
