Running header, a line as each phase starts, progress updates, and a closing verdict with a timing breakdown.
Console feature decides what those lines look like. It works like the CI status surfaces: a preset picks a whole layout by name, and templates override single lines on top of it. This guide describes Aspect CLI v2026.47.12 or later.
Only Aspect’s own lines are templated. Bazel’s output, the task’s own output, WARNING: and ERROR: lines, and stdout are never changed.
Picking a layout
The presets:
Pick one for a single run with a flag:
.aspect/config.axl:
.aspect/config.axl
config.axl, so a repository that defaults to plain can still run one task with --console:template-preset=full. Disabling the feature (--console:enabled=false) gives the full layout.
compact prints one line, for a coding agent or a long CI log:
Customizing a line
Each line Aspect prints comes from a slot, and each slot is a Jinja2 template. Setargs.templates to override any of them; slots you leave out keep the preset’s template:
.aspect/config.axl
"banner": "" drops the banner and keeps everything else.
Slots and their variables
Every slot gets these two:
highlight_style and highlight_reset are the ANSI codes that open and close a line’s highlight; both are empty when color is off. Color is on when stderr is a terminal, or on GitHub Actions, Buildkite, CircleCI or GitLab CI, whose logs render it; ctx.console.color reports it. A variable a slot doesn’t get renders as empty.
banner
header
phase
progress
verdict
section
breakdown and plain_breakdown follow --task:timing-summary: short gives an inline breakdown, detailed (the default) a table, and total or none leaves them empty. timing is empty only under none. phases always holds every phase, including the synthetic init phase that the built-in breakdown hides when it is short.
One task at a time
Two more args apply to one task, keyed by its kind or its command path.task_presets gives the task a preset of its own, and task_templates overrides its slots:
.aspect/config.axl
worktree add), to tell it apart from a task of the same kind in another group. A command-path entry beats an entry for the bare kind.
The layers resolve in order, lowest precedence first: the task’s task_presets entry, else template_preset with your templates on top, then the task’s task_templates for its kind, then for its command path. templates goes with template_preset, so a task with its own preset leaves it out: "worktree add": "silent" prints none of Aspect’s own lines for that task, even though templates sets a progress line for every other one. On Buildkite it still prints the section markers.
A preset typed on the command line, such as --console:template-preset=full, applies to every task for that run, task_presets included. That is the quick way to see everything while debugging a quiet task.
An entry for a task the repository doesn’t define is ignored rather than refused, so a user-level ~/.aspect/config.axl can carry entries for tasks only some repositories have.
Making your own layout
Override every slot to build a layout from scratch. This one prints one short line per phase and a terse verdict:.aspect/config.axl
full templates:
\n is a line break. The leading break on phase and verdict is the blank line that sets those lines apart. Jinja drops one trailing line break from a template, which is why the banner ends with two.
Write a template as one string, or join pieces with
+ as in the example above. In a triple-quoted string, the line break after the opening quotes becomes part of the line.On Buildkite
On Buildkite, the header, phase, verdict and section lines open collapsible log sections. Aspect prints the section marker (---, or +++ for an expanded one) itself, and your template supplies the text after it:
^^^ +++ line expands the phase that was running when the task failed.
Under any layout:
- A section always has a title. Leading whitespace in the text is dropped, so a terminal-style template that starts with a line break still titles its section.
- A section always prints. If the text is blank, the preset’s own text is used, and the
fulltext if the preset leaves the slot blank too. That is whycompactandsilentstill show phase sections and the failing-phase expansion on Buildkite.
buildkite in a template to print differently there:
When a template is wrong
Aspect checks your templates when it readsconfig.axl, before the task starts:
A template can also fail while it renders, for example by reading an attribute of a variable that isn’t set. That line falls back to the preset’s template, with one
WARNING: per slot.
Using the console from your own tasks
The built-in tasks print their phase and progress lines through the console, so those follow your layout automatically. A task of your own prints whatever it likes; to follow the selected layout, readctx.console.template_preset, or render a slot yourself. ctx.console.color says whether the console lines carry color, for a highlight_style you pass in:
.aspect/my_task.axl
ctx.console.render(slot, **context) returns the rendered text, or "" when the layout leaves the slot blank, as compact and silent do for progress; print nothing then.
See also
- How to customize CI status surfaces — the same preset and template model for GitHub checks, PR comments, GitLab and Buildkite annotations.
- Built-in features reference — every
Consoleoption and its flag.

