Selecting with Phases and Scopes

Selecting with Phases and Scopes

This page covers how workflows and the CLI select phase+scope pairs and what syntax is supported.

Workflows

A workflow is a list of phase+scope invocations. Each entry must include both fields:

workflow("build", {
    { phase = "configure", scope = "default" },
    { phase = "build",     scope = "default" },
    { phase = "test",      scope = "unit" },
})

beez build

Sequential workflow steps

Entries run in list order. Each entry waits for the previous one to finish.

workflow("pipeline", {
    { phase = "generate", scope = "code" },
    { phase = "compile",  scope = "code" },
})

Parallel workflow step

Run several pairs at the same time:

workflow("ci", {
    { parallel = {
        { phase = "generate", scope = "docs" },
        { phase = "generate", scope = "code" },
    }},
    { phase = "compile", scope = "code" },
})

Timeline:

generate:docs  -----|
generate:code  -----|  parallel
                    v
compile:code   -----

Each table inside parallel needs phase and scope. An empty parallel table is a load error.

CLI: -p / --phase

Run steps by phase without defining a workflow:

beez -p build:default
beez -p test:unit,integration
beez -p generate

Syntax reference

Form	Example	Behavior
phase	beez -p build	All scopes for build, sorted alphabetically, run one after another
phase:scope	beez -p build:default	One scope
phase:s1,s2	beez -p test:unit,integration	Listed scopes, in order
phase["s1","s2"]	beez -p generate["code","docs"]	Same as comma form; quotes required

Invalid -p syntax

These fail at CLI parse time:

Input	Problem
(empty)	No phase
:code	Missing phase
build:	Missing scope after colon
build:unit,	Trailing comma

Scope order when omitted

beez -p build discovers scopes from registered steps and sorts them alphabetically. You do not control order except by naming scopes or listing them explicitly:

beez -p build:zebra,alpha    # runs zebra, then alpha (your order)
beez -p build                 # runs alpha, then zebra (alphabetical)

Listing registered pairs

beez --list phases

Example output:

phases:

| Phase    | Scopes              |
|----------|---------------------|
| build    | [debug, default]    |
| test     | [integration, unit] |

beez --list steps

Shows each step's name, phase, scope, and description.

Comparison: workflow vs -p vs target

	Workflow	-p	Task / -s
Defined in	build.lua	CLI only	build.lua + CLI
Selects by	phase+scope pairs	phase+scope pairs	step name or shell
Parallel scopes	parallel in workflow	No (scopes sequential)	No
Reusable name	beez ci	Repeat full -p arg	beez my-task

Invocation priority

If you pass multiple run modes, Beez uses this priority:

1. --list
2. -s / --step
3. -p / --phase
4. Positional workflow/task target

See CLI Overview.

Examples

Run one toolchain variant:

beez -p configure:debug
beez -p build:debug

Run all tests:

beez -p test

CI workflow with parallel codegen:

workflow("ci", {
    { parallel = {
        { phase = "generate", scope = "api" },
        { phase = "generate", scope = "client" },
    }},
    { phase = "build", scope = "default" },
    { phase = "test", scope = "unit" },
})

beez ci

Next steps

• How Phases and Scopes Work - matching and execution model
• Workflow Declaration - full workflow DSL
• Filtering by Phase - CLI flag details
• Running a Single Step - -s bypasses phase selection