Step Declaration

Step Declaration

step({
    name = "compile",
    phase = "build",
    scope = "default",
    description = "Build the project",
    input = { "src/**/*.cpp" },
    output = { "build/app" },
    mutate = { "src/**/*.cpp" },
    config = { optimize = true },
    run = "cmake --build build",
})

Required fields

Field	Type	Description
name	string	Unique step name (used by -s, order(), tasks)
phase	string	Phase label (you choose the name)
scope	string	Scope label within the phase
run	string or function	Shell command or Lua callback

Optional fields

Field	Type	Description
description	string	Shown in progress UI when set
input	string array	Glob patterns of files the step reads
output	string array	Glob patterns of files the step creates
mutate	string array	Glob patterns of files the step changes in place
config	table	Step-specific config (see Configure Step)

Array fields use Lua list syntax with integer keys:

input = { "src/**/*.cpp", "include/**/*.hpp" }

Only string entries are allowed.

Shell run

run = "ninja -C build"

Beez runs the command in the project root via the shell executor (cd <root> && <command>).

Exit code 0 means success. Any other code fails the step.

Lua run callback

run = function(ctx)
    local files = ctx.glob({ "src/**/*.cpp" })
    if #files == 0 then
        return 0
    end
    -- custom logic
    return 0
end

The callback receives a step context table (ctx). See Step Context.

Return value

Return	Meaning
0 or nothing	Success
Non-zero integer	Failure (step fails)

Non-integer return values are treated as success (0).

On Lua error, Beez prints Lua step error: and the step fails with exit code 1.

Artifact patterns and caching

Steps with at least one of input, output, or mutate are step-cacheable.

Pattern	Typical use
input	Files whose content is read (hashed for cache key)
output	Files created or replaced
mutate	Files changed in place (also affects ordering; see Order Declaration)

Steps without artifact patterns always run (no step cache skip).

Details: Step Cache and Artifact Patterns.

Phase and scope

phase and scope group steps for workflows and beez -p. They are free-form strings. See Phases and Scopes.

Examples

Simple shell step:

step({
    name = "test",
    phase = "test",
    scope = "unit",
    run = "ctest --test-dir build",
})

Step with description and artifacts:

step({
    name = "link",
    phase = "build",
    scope = "default",
    description = "Link the application",
    input = { "build/**/*.o" },
    output = { "build/app" },
    run = "cmake --build build --target app",
})

Lua callback with glob:

step({
    name = "lint",
    phase = "qa",
    scope = "default",
    mutate = { "src/**/*.cpp" },
    run = function(ctx)
        local config = ctx.get_config()
        local files = ctx.glob(config.patterns)
        -- per-file lint logic
        return 0
    end,
})

Next steps

• Step Context - ctx API
• Configure Step - external config tables
• Order Declaration - dependencies between steps