Config Reference

Config Reference

All Beez settings use dotted paths (for example cache.compress.level). Discover keys and allowed enum values from the CLI:

beez --config-options
beez --config-options ui.animation.indicator

This page lists every key. Defaults shown here are what Beez uses when nothing overrides them.

performance

Key	Type	Default	Description
performance.max_threads	integer (1-1024)	CPU core count	Max parallel worker threads
performance.cache_write_strategy	enum	phase	immediate, phase, end
performance.cache_fs_metadata	boolean	true	Cache glob metadata per run
performance.use_mmap_for_hashing	boolean	true	Use mmap for large file hashes
performance.mmap_hashing_min_bytes	integer (>=1)	65536	Min size for mmap hashing
performance.optimize_gc_for_throughput	boolean	false	Reduce Lua GC during runs
performance.pin_threads_to_cores	boolean	false	Pin workers to CPU cores

cache

Key	Type	Default	Description
cache.path	path	.cache	Cache root directory
cache.enabled	boolean	true	Enable step and success cache
cache.protect	boolean	false	Protect cache files on write
cache.hash.algorithm	enum	fnv1a64	fnv1a64, fnv1a32, crc32, djb2, sdbm
cache.hash.seed	uint32	0	Hash seed
cache.compress.algorithm	enum	none	none, gzip, zlib, rle, deflate, delta, vbyte
cache.compress.level	integer (0-9)	6	Compression level
cache.compress.mode	enum	auto	never, always, auto

ui

Key	Type	Default	Description
ui.output_mode	enum	clean	clean, verbose, errors, silent
ui.colors	boolean	true	Enable ANSI colors
ui.truecolor	boolean	follows colors	Use 24-bit colors
ui.theme	string	unset	Name of entry in ui.themes
ui.themes	map	unset	Named color palettes
ui.icons	boolean	true	Show status icons
ui.animation.progress	enum	minimal	minimal, lines, blocks, custom
ui.animation.indicator	enum	step	step, percent, minimal, dots, custom
ui.animation.indicator_spin_interval	number	80	Spinner interval (ms)
ui.animation.spinner	enum	legacy alias	Accepted alias for ui.animation.indicator
ui.log_level	enum	info	info, warn, error
ui.hide_cache_hits	boolean	false	Hide cache hit lines
ui.prefix	boolean	false	Show worker prefix
ui.prefix_format	string	[Worker {id}]	Worker prefix format
ui.show_time_saved	boolean	true	Show cache time saved in summary
ui.summary	enum	simple	minimal, simple, compact, data
ui.logging.run_log	boolean	true	Write run log file
ui.logging.run_log_file	path	.cache/logs/latest.log	Run log path
ui.logging.log_steps	boolean	false	Verbose step logging in run log
ui.logging.workers	enum	on_failure	off, on_failure, always
ui.logging.workers_dir	path	.cache/logs/workers	Worker log directory

env

Key	Type	Default	Description
env.load_dotenv	boolean	true	Load .env from project root
env.dotenv_overrides_system	boolean	false	Dotenv overwrites existing env
env.files	path or list	unset	Extra env files to load
env.vars	string map	{}	Default env vars (always applied)
env.hash_vars	string list	see below	Vars in cache fingerprint
env.ignore_vars_for_hashing	string list	see below	Excluded from fingerprint
env.mask_secrets	string list	see below	Redacted in logs

Default env.hash_vars: CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, BUILD_TYPE

Default env.ignore_vars_for_hashing: TERM, COLORTERM, PWD, SESSION_ID

Default env.mask_secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, NPM_AUTH_TOKEN

List fields accept a single string or a Lua array:

hash_vars = { "CC", "CXX" }
-- or
hash_vars = "CC"

CLI overrides (not in config files)

Flag	Config equivalent
--verbose	ui.output_mode = verbose
--error	ui.output_mode = errors
--silent	ui.output_mode = silent
--dry-run	Skips shell commands and Lua callbacks
--no-cache	cache.enabled = false
-j N, --threads N	performance.max_threads = N
--log-file PATH	ui.logging.run_log = true, ui.logging.run_log_file = PATH
--no-log-file	ui.logging.run_log = false

Keeping this page up to date

The schema in Beez is the source of truth. If a key is missing here, run:

beez --config-options

beez --show-config shows effective values and origins for your current project.

Related pages

• Configuration Overview - merge order
• Performance Settings - tuning guide
• Cache Settings - cache tuning guide
• UI and Output - themes, progress, summaries, and log files
• Environment Variables - env and fingerprints
• Appendix - glossary and quick reference