Logging and Log Files

Logging and Log Files

Terminal output mode controls what you see live. Run logs and worker logs are written separately under ui.logging and are useful for CI artifacts and post-mortem debugging.

ui = {
    logging = {
        run_log = true,
        run_log_file = ".cache/logs/latest.log",
        log_steps = false,
        workers = "on_failure",
        workers_dir = ".cache/logs/workers",
    },
}

Paths are relative to the project root unless absolute.

Run log

run_log

When true (default), Beez writes a text log for the whole run.

run_log_file

Destination file. Default: .cache/logs/latest.log.

The parent directory is created automatically.

CLI overrides:

beez --log-file /tmp/beez.log build
beez --no-log-file build

What goes in the run log

Content	Always	Notes
Start banner	yes	Target or phase name
Run summary	yes	Same lines as console when summary is shown
Progress lines	no	Only when log_steps = true
Verbose worker output	no	Worker logs are separate (below)

Run log content respects ui.log_level for Beez log messages.

Step logging (log_steps)

When log_steps = true, each progress line is duplicated to the run log file. Useful when you want a chronological step list without enabling verbose console output.

ui = {
    output_mode = "clean",
    logging = {
        run_log = true,
        log_steps = true,
    },
}

Animated spinner mode still writes discrete progress lines to the file when log_steps is enabled.

Worker logs

Subprocess output can be captured to per-worker files under workers_dir.

workers

Value	Behavior
off	Never write worker log files
on_failure	Write when a worker fails (default)
always	Always write worker log files

Worker logs are independent of output_mode. You can run clean on the console and still retain full worker output on disk with workers = "always".

workers_dir

Default: .cache/logs/workers/.

Each worker channel gets its own file. After a failed run:

ls .cache/logs/workers/
beez --verbose -j 1 -s failing-step   # reproduce with live output

Console vs files

Data	Console (clean)	Console (verbose)	Run log	Worker logs
Progress	yes	yes	if log_steps	no
Success command output	no	yes	no	if always
Failure command output	yes	yes	no	on failure or always
Summary	yes	yes	yes	no

Related pages

• Output Modes - live terminal behavior
• Progress and Animation - progress line format
• Output and Logging Flags - --log-file, --no-log-file
• Project Layout - .cache/logs/ in the project tree
• Config Reference - all ui.logging.* keys