Progress and Animation

Progress and Animation

While steps run, Beez updates a progress line for each unit of work. In clean mode on an interactive terminal, non-cached steps can use an animated spinner instead of printing a new line per step.

Progress line format

Each progress event has:

• Category - the step phase name, or step when no phase is set.
• Detail - the step description if set, otherwise the step name.

Example:

compile | Compile shaders

Cached steps append (cached) to the category and use the cache_hit theme color:

compile (cached) | Compile shaders

Hiding cache hits

When ui.hide_cache_hits = true, Beez does not print progress lines for cache hits. The internal progress counter still advances, so indicators and summaries stay consistent.

ui = {
    hide_cache_hits = true,
}

Animation config

ui = {
    animation = {
        progress = "minimal",
        indicator = "step",
        indicator_spin_interval = 80,
    },
}

Legacy keys ui.animation.spinner and nested progress.numbers are still accepted for compatibility.

Progress bar style (animation.progress)

Value	Result
minimal	Indicator + category + detail (no bar)
lines	Bar with line characters + indicator + text
blocks	Bar with block characters + indicator + text
custom	Bar from a custom table (see below)

Custom progress table (also used when progress is a table):

ui = {
    animation = {
        progress = {
            start = "[",
            end_delimiter = "]",
            fill = "=",
            empty = "-",
            indicator = "percent",  -- optional, same as top-level indicator
        },
    },
}

Indicator style (animation.indicator)

Controls the leading segment (step counter, percent, or spinner).

Value	Behavior
step	Current index and total, e.g. 3/12
percent	Rounded percentage
minimal	Compact spinner (`
dots	Animated dot spinner (requires icons = true for default frames)
custom	Cycles through custom frames

Custom indicator as a frame list:

ui = {
    animation = {
        indicator = { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" },
        indicator_spin_interval = 80,
    },
}

Custom indicator as a config table:

ui = {
    animation = {
        indicator = {
            type = "custom",
            frames = { "|", "/", "-", "\\" },
            start = "[",
            end_delimiter = "]",
            spin_interval = 100,
        },
    },
}

indicator_spin_interval is in milliseconds. Animation runs only when the interval is greater than zero and the indicator style uses a spinner.

When animation runs

Animated spinners are used when all of these hold:

• Output mode is clean
• stdout is a TTY
• The step is not a cache hit
• The indicator style is spinner-based (minimal, dots, or custom frames)
• indicator_spin_interval is greater than 0

Otherwise Beez prints a full progress line per step (still respecting hide_cache_hits).

If icons = false and the indicator would be dots, Beez falls back to minimal automatically.

Log level

ui.log_level filters Beez's own log messages (info, warn, error). It applies to console and run log loggers.

ui = {
    log_level = "warn",
}

This does not suppress progress lines or subprocess output; use Output Modes for that.

Related pages

• Output Modes - which modes show progress
• Colors and Themes - colors used on progress lines
• Caching - cache hits in progress output
• Step Declaration - description and phase fields