CLI Reference

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

Usage

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

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

Export an animated GIF

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

Custom rule with video export

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

CSV statistics

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)

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

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