Lua API Overview

Lua API Overview

Beez scripts (build.lua) and Lua step callbacks have access to a global beez table. Use it to read configuration, touch the filesystem, fetch URLs, hash artifacts, and more — without shelling out for every task.

All file paths in the Lua API are relative to the project root (the directory that contains build.lua).

---

Modules at a glance

Module	Example	What it does
beez.env	beez.env("TOKEN")	Environment variables and .env
beez.config	beez.config({ cache = { ... } })	Project settings
beez.fs	beez.fs.glob("src/**/*.cpp")	Files and directories
beez.crypto	beez.crypto.hash_file("app.zip")	Hashes and encodings
beez.sys	beez.sys.cpu_threads()	Host information
beez.time	beez.time.now()	Clock and sleep
beez.date	beez.date.format("%Y-%m-%d")	Calendar formatting
beez.data	beez.data.deserialize_file("cfg.json")	JSON/YAML/XML/CSV/TOML
beez.net	beez.net.get(url, headers)	HTTP and downloads
beez.archive	beez.archive.compress("dist", "out.zip")	zip/tar archives
beez.text	beez.text.template("Hello {{name}}", vars)	Strings and templates
Workers	ctx:spawn({ cmd = "make" })	Background shell in a step

Developer reference (same content, in-repo): docs/lua-api-overview.md

---

Where APIs are available

Context	beez.*	ctx:spawn / wait
Top-level build.lua	yes	no
step({ run = function(ctx) ... })	yes	yes

---

Error handling

• Invalid arguments and I/O errors usually throw a Lua error.
• beez.net.* REST helpers return { ok = false } for HTTP 4xx/5xx; network failures throw.
• beez.data.validate throws when data does not match the schema.

---

Example build script

beez.config({
    cache = { enabled = true },
})

local version = beez.env("RELEASE_VERSION") or "dev"
local artifacts = beez.fs.glob("dist/**/*")

step({
    name = "upload",
    phase = "publish",
    scope = "release",
    run = function(ctx)
        beez.archive.compress("dist", "bundle-" .. version .. ".zip")
        local hash = beez.crypto.hash_file("bundle-" .. version .. ".zip", "sha256")
        print("uploading", hash)
        return 0
    end,
})

---

See also

• DSL Overview — tasks, steps, workflows
• Lua API Workers — parallel shell inside a step
• CHANGELOG