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)

See Environment Variables for env.files, env.vars, and related config.

beez.env_or(key, …, default)

Read an environment variable, or return a default string if unset.

local buildType = beez.env_or("BUILD_TYPE", "Release")
local scanner = beez.env_or("OSV_SCANNER", beez.env_or("HOME", "") .. "/.local/bin/osv-scanner")

With multiple keys before the default, each key is tried in order (first hit wins).

beez.shell.run(ctx, log_prefix, command [, options])

Run a shell command synchronously inside a step callback (uses ctx:spawn + ctx:wait internally).

local code = beez.shell.run(ctx, "[mytool]", "make -j8")

Option	Meaning
return_output = true	Return exit code and output as a pair (result.first, result.second)

beez.char.quote(text)

Escape a string for safe use inside shell single-quoted arguments.

task("demo", "echo " .. beez.char.quote("it's fine"))

beez.increment.run(ctx, config)

Incremental multi-file tool runner (parallel workers, success cache). See Plugin System.

Other beez.* modules

This page covers configuration, environment, and plugin helper APIs on the root beez table.

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
beez.shell / beez.char / beez.increment	Plugin System
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
• Plugin System - plugins, configure(), standard workflows