Beez API

Beez API

The beez table exposes project settings and environment access from build.lua.

beez.config(table)

Merge project Beez settings (cache, UI, performance, env).

beez.config(require("config"))

beez.config({
    cache = { enabled = true },
    ui = { output_mode = "clean" },
})

• Multiple calls merge; later calls override the same keys
• Same shape as ~/.config/beez/config.lua (see Configuration)
• Applied when the script loads, before any step runs

Typical pattern at the top of build.lua:

beez.config(require("config"))

beez.env(key)

Read an environment variable by name.

local buildType = beez.env("BUILD_TYPE")
local cc = beez.env("CC") or "gcc"

Lookup order

1. Process environment (getenv), including values from env.vars and env files already loaded by applyEnvironment()
2. Project root .env file (lazy-loaded on first beez.env() call)
3. nil if unset (Lua nil, not empty string)

beez.env() does not read every env.files entry directly. Files listed under env.files become visible after beez.config() runs, because that call applies them to the process environment. Call beez.config(require("config")) before reading project env vars at the top of build.lua.

Use beez.env() when defining shell commands or step logic at load time:

local BUILD_TYPE = beez.env("BUILD_TYPE") or "Release"
local BUILD_TREE = "build/build/" .. BUILD_TYPE

Related config

Control env loading via the env section in config:

• load_dotenv, files, vars, hash_vars, etc.

See Environment Variables.

What is not on beez

Feature	Where
Register steps	Global step()
Run commands	CLI (beez ...)
Read cache	Step context in callbacks

Next steps

• Configuration - full config reference
• Project Config - config.lua pattern
• DSL Overview - other globals