Global User Config

Global User Config

Machine-wide Beez preferences live in a single Lua file outside any project.

Location

~/.config/beez/config.lua

If XDG_CONFIG_HOME is set:

$XDG_CONFIG_HOME/beez/config.lua

Beez loads this file automatically on every run. You do not reference it from build.lua.

If the file is missing or HOME is unset, Beez skips global config and uses defaults plus project settings.

Creating the file

Copy the example from the Beez repository:

mkdir -p ~/.config/beez
cp scripts/config.lua.example ~/.config/beez/config.lua

Edit the copy to match your preferences.

Minimal example

return {
    performance = {
        max_threads = 8,
    },

    ui = {
        output_mode = "clean",
        colors = true,
        theme = "gruvbox",
        themes = {
            gruvbox = {
                text = "#ebdbb2",
                muted = "#928374",
                success = "#b8bb26",
                error = "#fb4934",
            },
        },
    },
}

Good uses for global config

Use case	Example setting
Preferred thread count	performance.max_threads
Personal color theme	ui.theme, ui.themes
Quieter default output	ui.output_mode = "errors"
Disable cache globally (unusual)	cache.enabled = false
Default env vars for all projects	env.vars

What to keep in the project instead

Put settings in project config.lua when they belong to the repo:

• Toolchain variables (CC, BUILD_TYPE, ...)
• Cache path relative to the project
• CI-relevant env defaults
• Anything teammates should share via git

Global config is for personal taste and machine-specific defaults.

Priority

Project beez.config() overrides global config for the same key. CLI flags override both.

Verify the result:

cd my-project
beez --show-config

The origin column shows whether a value came from global, project, default, or CLI.

Next steps

• Project Config - repo-level settings
• Configuration Overview - full merge order
• UI and Output - theme and output options