CLI

CLI

vivarium [flags]              # GUI
vivarium headless [flags]     # no display, streams CSV

The GUI is the default. headless runs the same simulation with no Ebiten or display dependency.

---

Shared flags

Both accept the population and world settings:

Flag	Default	Description
--seed <n>	1	Random seed for reproducible runs
--plants <n>	from config	Initial plant count
--herbivores <n>	from config	Initial herbivore count
--carnivores <n>	from config	Initial carnivore count
--width <f>	from config	World width
--height <f>	from config	World height
--rescue	from config	Rescue effect on/off
--config <file>	—	JSON config overriding defaults
--load <file>	—	Start from a saved population snapshot

Defaults for the population and size flags come from the config, so they stay in step with Configuration rather than being duplicated.

---

headless-only flags

Flag	Default	Description
--ticks <n>	10000	Number of ticks to simulate
--every <n>	200	Emit a stats row every N ticks
--save <file>	—	Write the final population snapshot here
--print-config	false	Print the default config as JSON and exit

See Headless runs for the experiment workflow.

---

Examples

# GUI, reproducible
go run ./cmd/vivarium --seed 42

# A denser starting world
go run ./cmd/vivarium --plants 400 --herbivores 120 --carnivores 20

# Long offline experiment
go run ./cmd/vivarium headless --ticks 50000 --every 200 --save evolved.json > run.csv

# Open an evolved population in the GUI
go run ./cmd/vivarium --load evolved.json

---

Linux dependencies

The GUI needs the usual Ebiten build dependencies:

sudo apt install libgl1-mesa-dev xorg-dev libxxf86vm-dev libasound2-dev

headless needs none of these — it is display-free, which is what makes it usable in CI and on servers.