12. The cook CLI — cook docs

cook --help is the source of truth; this is the friendly version.

cook [OPTIONS] [COMMAND]

With no command, cook runs the build recipe. A recipe name runs that recipe; a subcommand name runs the subcommand. Prefix a recipe with + when its name collides with a subcommand.

Everyday

Command	Does
`cook` / `cook <recipe> [preset]`	run a recipe (default `build`), optionally with a config `@preset`
`cook init`	scaffold a starter Cookfile and `.gitignore`
`cook menu` / `cook list`	list recipes and chores, with each chore’s parameters
`cook test [scope]`	run tests (`--filter`, `--fail-fast`, `--rerun-failed`, `--report-json`, `--report-junit`)
`cook serve [recipe]`	watch gather and re-run on change

Investigation

Command	Does
`cook why [recipe]`	explain what a run would do: the build graph with per-node hit/rebuild counts, what each rebuild invalidates downstream, and last-observed timings. `--level recipe\|group\|unit`, `--format text\|mermaid\|dot\|json`, `--unit <pat>` for one unit’s full determinants. Read-only
`cook cache du`	report local artifact-store disk usage: total, breakdown by artifact kind and recipe namespace, oldest/newest, and budget usage when `[cache] max_size` is set
`cook cache verify [recipe]`	re-run cached steps, fail on byte-divergence (`--json`)
`cook cache gc --max-size <N>\|--older-than <dur>`	evict least-recently-used or stale artifacts from the local store (`10GB`/`20GiB`, `30d`/`720h`); `--dry-run` to preview. `[cache] auto_gc` runs the size sweep for you
`cook logs [id]`	browse the per-build log archive (`-n N` for the Nth most recent, `--last-failed`)
`cook emit-lua`	print the Lua a Cookfile compiles to
`cook affected --since=<ref>`	list recipes whose inputs changed since a git ref (`--recipe`, `--json`)

Modules

cook modules install [names…] | remove <names> | update [name] | list | search <query>: with --registry, --non-interactive, and --accept-trust for CI.

Global flags worth knowing: -f/--file, --root, -j/--jobs, -q/--quiet, -v/--verbose, --color, --output auto|plain|json, --set KEY=VALUE (repeatable), --since <ref> + --affected, --no-prune, --no-auto-gc (skip the [cache] auto_gc sweep for this run; the over-budget warning still prints), --no-publish.

Tab completion is served by the cook binary itself, so it always matches the Cookfile in front of you: it completes your recipes and chores (and config presets after @), not just the built-in subcommands. Add one line to your shell’s startup file:

COMPLETE=fish cook | source

# ~/.bashrc
source <(COMPLETE=bash cook)

# ~/.zshrc
source <(COMPLETE=zsh cook)

elvish and powershell work the same way.

For CI, the pattern is:

cook test --affected --since=origin/main    # only test the slice the PR touched