Quick Reference

Quick Reference

One-page cheat sheet for daily use. See linked pages for full detail.

CLI

# Run
beez build                          # workflow or task named "build"
beez -p compile                     # all scopes in phase "compile"
beez -p test:unit                   # phase "test", scope "unit"
beez -s compile                     # single step by name
beez -j 8 build                     # limit worker threads

# Inspect
beez --list steps                   # tasks | workflows | steps | phases
beez --show-config
beez --config-options cache.hash.algorithm

# Scaffold (beta; no build.lua — see [[Project Scaffolding]])
beez --init list
beez --init info basic_cpp
beez --init basic_cpp ./my-app --set project_name="My App"

# Output
beez --verbose build
beez --silent build
beez --error build

# Cache (--clean-cache and --update need build.lua for the configured cache path)
beez --no-cache build
beez --clean-cache build
beez --update

# Debug
beez build --dry-run
beez -s my-step --verbose

# Dependencies (ReqPack)
beez --install                      # install all reqpack { ... } packages
beez --install --dry-run            # show rqp command only

Flag priority

--list > -s / --step > -p / --phase > positional target

Phase argument examples

Argument	Meaning
compile	Phase compile, all scopes (alphabetical)
compile:code	Phase compile, scope code
test:unit,integration	Phase test, scopes run sequentially
generate["code","docs"]	Phase generate, listed scopes

Minimal build.lua

beez.config(require("config"))   -- optional

reqpack {
    sys = { "make" },
    npm = { { name = "typescript", version = "5.0.0" } },
}

step({
    name = "hello",
    phase = "demo",
    scope = "default",
    run = "echo hello",
})

task("hi", "echo hi")

workflow("all", {
    { phase = "demo", scope = "default" },
})

beez -s hello                    # step named "hello"
beez hi                          # task "hi"
beez all                         # workflow "all"

Cacheable step

step({
    name = "compile",
    phase = "build",
    scope = "default",
    input = { "src/**/*.cpp" },
    output = { "build/app" },
    run = "g++ -o build/app src/main.cpp",
})

Lua callback step

step({
    name = "process",
    phase = "build",
    scope = "default",
    run = function(ctx)
        local files = ctx.glob({ "data/**/*.json" })
        -- ...
        return 0   -- exit code
    end,
})

Parallel workflow

workflow("ci", {
    { parallel = {
        { phase = "lint", scope = "code" },
        { phase = "test", scope = "unit" },
    }},
    { phase = "package", scope = "default" },
})

Config skeleton (config.lua)

return {
    performance = { max_threads = 8 },
    cache = { path = ".cache", enabled = true },
    ui = {
        output_mode = "clean",
        summary = "simple",
        logging = { run_log = true },
    },
    env = {
        load_dotenv = true,
        vars = { BUILD_TYPE = "Release" },
    },
}

Project layout (user project)

my-project/
  build.lua
  config.lua          -- optional
  .env                -- optional
  .cache/             -- cache + logs (default)
  .cache/reqpack/     -- reqpack install fingerprints (when using reqpack { ... })
  src/

Exit codes

Code	Typical cause
0	Success, --help, --version
1	Command/step failure, parse error, missing target, invalid flags

Related pages

• CLI Flag Reference - every flag
• Config Reference - every config key
• DSL Overview - full DSL surface
• ReqPack Declaration - external dependencies
• First Pipeline - guided tutorial