Configuration
Every build option can be set in three places. They layer, lowest precedence first:
built-in defaults → ~/.zutrc → ./.zutrc → command-line flags
So a project .zutrc overrides your personal ~/.zutrc, and an explicit flag
always wins. Each option is defined exactly once internally — the flag parser
and the .zutrc loader funnel through the same code — so a .zutrc key and its
flag always have the same name and meaning.
The .zutrc file
A flat key = value file, # for comments. Keys match the flag names (without
the leading --); a bare boolean is written key = true.
# ~/.zutrc or ./.zutrc
sandbox = namespace
jobs = 8
remote-cache = s3://my-bucket?region=eu-west-3
remote-cache-mode = read-write
log-level = info
A malformed or unknown value in .zutrc is advisory: zut warns and ignores
it (config never hard-fails a build). An unknown or malformed command-line
flag, by contrast, is an error — typos on the CLI shouldn’t pass silently.
Reference
| Key / flag | Values | Default | Notes |
|---|---|---|---|
sandbox | prep, namespace, landlock | strongest available | Sandboxing |
jobs | positive integer | CPU count | parallel actions |
profile | bool | false | per-action timing table |
remote-cache | a backend spec | none | cmd:/fs:/s3:/gs: |
remote-cache-mode | read, read-write | read-write | |
log-level | error/warn/info/debug/trace/off | info | Logging |
verbose | bool | false | alias for log-level = debug |
quiet | bool | false | alias for log-level = off |
Environment variables
ZUT_LOG— sets the initial log level before any.zutrc/flag is applied (handy for one-off debugging:ZUT_LOG=trace zut build //:x).NO_COLOR— disables colored output (also auto-disabled when stderr is not a terminal).- AWS / GCS credential variables for the remote cache — see Remote caching.