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.

Other beez.* modules

This page covers configuration (beez.config) and environment (beez.env) only.

For filesystem, crypto, HTTP, archives, data serialization, text templates, and more, see Lua API Overview.

Module	Page
beez.fs	Lua API Filesystem
beez.crypto	Lua API Crypto
beez.sys	Lua API System
beez.time / beez.date	Lua API Time and Date
beez.data	Lua API Data (includes schema validation)
beez.net	Lua API Network
beez.archive	Lua API Archive
beez.text	Lua API Text
ctx:spawn / wait	Lua API Workers

What is not on beez

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

Next steps

• Lua API Overview - full beez.* reference
• Configuration - full config reference
• Project Config - config.lua pattern
• DSL Overview - other globals