Configuration Overview

Configuration Overview

Beez builds one active configuration for each run by merging several sources. Later sources override earlier ones for the same key.

Merge order

From lowest to highest priority:

Priority	Source	Where
1	Global user config	~/.config/beez/config.lua (or $XDG_CONFIG_HOME/beez/config.lua)
2	Project config	beez.config({ ... }) in build.lua (often via require("config"))
3	Environment	.env files and env.vars from config
4	CLI flags	--verbose, --no-cache, -j, etc.

Startup flow

When you run a target (workflow, task, phase, or step), Beez roughly does this:

1. Load global config.lua if it exists
2. Apply environment settings once (dotenv + env.vars)
3. Load build.lua and merge project beez.config(...)
4. Apply environment settings again (project may have changed env options)
5. Apply CLI overrides
6. Run the requested target

Environment is applied twice so project-level env settings take effect before the final merge with CLI flags.

Config file format

All config files are Lua modules that return a table:

return {
performance= { ... },
cache= { ... },
ui= { ... },
env= { ... },
}

Top-level keys:

Key	Purpose
performance	Threads, cache write timing, hashing behavior
cache	Cache directory, enable/disable, hash and compression
ui	Terminal output, colors, progress, summaries, logging
env	Dotenv loading, default vars, cache fingerprint vars

You only need to include the sections you want to override.

Inspecting configuration

Show merged settings

beez --show-config

Prints the active values and shows which layer set each one (global, project, CLI, or default). You must run this from a directory that contains a build.lua, because project config is loaded from there.

Discover keys and enum values

beez --config-options
beez --config-options performance
beez --config-options cache.compress.mode

Without a path, lists child keys. At a leaf enum key, lists allowed values.

CLI overrides

These flags change behavior for a single run (most map to a config key):

Flag	Effect
--verbose	ui.output_mode = verbose
--error	ui.output_mode = errors
--silent	ui.output_mode = silent
--dry-run	Run-only: load build.lua, build graph, show progress; skip shell commands and Lua callbacks (not a config file key)
--no-cache	cache.enabled = false
-j, --threads N	performance.max_threads = N
--log-file PATH	Enable run log at PATH
--no-log-file	Disable run log

See CLI Flag Reference for the full list of flags. Output and cache flags are described in Output and Logging Flags and Cache and Maintenance Flags.

What is not in config files

Some things are defined only in build.lua, not in Beez settings:

• Steps, tasks, workflows
• order() dependencies
• configure_step() data

Shell steps and Lua callbacks read the environment via beez.env("KEY") after env settings are applied.

Next steps

• Global User Config - per-machine defaults
• Project Config - per-repo overrides
• Environment Variables - .env and cache fingerprints