> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# How to customize task output in the terminal

> Choose how much Aspect CLI prints around a task, drop the emojis, or rewrite any of those lines in Jinja2 with the Console feature.

Around every task, Aspect CLI prints a few lines of its own: a banner, a `Running` header, a line as each phase starts, progress updates, and a closing verdict with a timing breakdown.

```
Aspect CLI v2026.47.12 — https://aspect.build/docs/cli

→ 🎬 Running test task

→ 🔧 Setup · Running setup

→ 🧪 Test · Spawning bazel test

→ ✅ Passed test task in 1.2s · Tests passed (cached)
    🔧 Setup   2ms  Prepare the task environment
    🧪 Test   1.2s  Run bazel tests
```

The `Console` feature decides what those lines look like. It works like the [CI status surfaces](https://aspect.build/docs/cli/guides/status-surfaces.md): 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:

| Preset | What it prints |
| - | - |
| `full` | Every line shown above. This is the default. |
| `plain` | The same lines without emojis or Buildkite emoji shortcodes. |
| `compact` | Only the verdict, on one line, without the phase breakdown. |
| `silent` | None of Aspect's own lines. The exit code and the task's own output carry the result. |

Pick one for a single run with a flag:

```bash theme={null}
aspect test //... --console:template-preset=compact
```

Or for the repository in `.aspect/config.axl`:

```python title=".aspect/config.axl" theme={null}
load("@aspect//feature/console.axl", "Console")

def config(ctx: ConfigContext):
    ctx.features[Console].args.template_preset = "plain"
```

The flag wins over `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:

```
→ ❌ Failed test task (exit code 3) in 4.1s · 2 of 40 tests failed
```

## Customizing a line

Each line Aspect prints comes from a **slot**, and each slot is a [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) template. Set `args.templates` to override any of them; slots you leave out keep the preset's template:

```python title=".aspect/config.axl" theme={null}
load("@aspect//feature/console.axl", "Console")

def config(ctx: ConfigContext):
    ctx.features[Console].args.templates = {
        "header": "▶ {{ highlight_style }}{{ label }}{{ highlight_reset }}",
    }
```

An empty template prints nothing, so `"banner": ""` drops the banner and keeps everything else.

### Slots and their variables

| Slot | When it prints |
| - | - |
| `banner` | Above the header, on a terminal or a recognized CI host, unless `ASPECT_CLI_NO_BANNER` is set |
| `header` | When the task starts |
| `phase` | On each update with text that names a phase; on Buildkite, only when the phase changes, as a section title |
| `progress` | On each update with text that names no phase; on Buildkite, also each update with text within the current phase |
| `verdict` | When the task returns; a task that fails with an error prints the error instead |
| `section` | When a task opens its own Buildkite log section, such as the Workflows runner metadata |

Every slot gets these two:

| Variable | Value |
| - | - |
| `buildkite` | `true` when the run is on Buildkite |
| `task` | The running task: `kind`, `group`, `name` and `path` (the command as typed, such as `worktree add`) |

`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`](#using-the-console-from-your-own-tasks) reports it. A variable a slot doesn't get renders as empty.

**`banner`**

| Variable | Value |
| - | - |
| `line` | The whole built-in line, in grey when color is on, such as `Aspect CLI v2026.47.12 — https://aspect.build/docs/cli`; a debug build adds ` (debug build)` |
| `version` | The CLI version |
| `debug_build` | `true` for a debug build |
| `docs_url` | The CLI docs link |
| `highlight_style`, `highlight_reset` | Grey, the banner's built-in color |

**`header`**

| Variable | Value |
| - | - |
| `label` | The task label: `<path> task` locally, such as `test task` or `worktree add task`; `<name> [<path>]` on CI or under `--task:name`, such as `unit-tests [test]`. For the bare command, use `task.path` |
| `highlight_style`, `highlight_reset` | The color of the built-in `Running`: bold cyan, or the SGR code in `ASPECT_CLI_HIGHLIGHT_COLOR`; an empty value leaves both empty |

**`phase`**

| Variable | Value |
| - | - |
| `text` | The update's text |
| `title` | The phase's display name, such as `Build` |
| `emoji` | The phase's emoji |
| `highlight_style`, `highlight_reset` | The phase title's color, the same as the header's, and set on the same hosts |

**`progress`**

| Variable | Value |
| - | - |
| `text` | The update's text |
| `title`, `emoji`, `highlight_style`, `highlight_reset` | As for `phase`, when the update names its phase; otherwise not set |

**`verdict`**

| Variable | Value |
| - | - |
| `verdict` | `passed`, `flagged` or `failed` |
| `verb` | `Passed`, `Flagged` or `Failed` |
| `glyph` | `✅`, `⚠️ ` or `❌` |
| `shortcode` | The matching Buildkite emoji shortcode, such as `:white_check_mark:` |
| `highlight_style`, `highlight_reset` | The verdict's color: green, yellow or red |
| `label` | The task label, as in the header |
| `exit_code` | The task's exit code |
| `exit` | ` (exit code 3)`, or empty on success |
| `elapsed`, `elapsed_ms` | The task's wall time, formatted (`1.2s`) and in milliseconds |
| `timing` | ` in 1.2s`, or empty under `--task:timing-summary=none` |
| `conclusion` | The task's one-line summary, such as `Tests passed (cached)` |
| `breakdown` | The phase breakdown as the built-in layout prints it |
| `plain_breakdown` | The same breakdown without phase emojis |
| `phases` | Every recorded phase, each with `name`, `title`, `emoji`, `description`, `duration`, `duration_ms` and `interrupted` |

**`section`**

| Variable | Value |
| - | - |
| `icon` | A Buildkite emoji shortcode such as `:rocket:`, or empty |
| `title` | The section's title, such as `Workflows runner metadata` |

`breakdown` and `plain_breakdown` follow [`--task:timing-summary`](https://aspect.build/docs/cli/tasks#flags-every-task-accepts): `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:

```python title=".aspect/config.axl" theme={null}
ctx.features[Console].args.templates = {"progress": "· {{ text }}"}
ctx.features[Console].args.task_presets = {
    "test": "compact",
    "worktree add": "silent",
}
ctx.features[Console].args.task_templates = {
    "lint": {"verdict": "{{ glyph }} lint {{ verb }}{{ timing }}"},
}
```

Key a task in a group by its command path, as typed (`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](#on-buildkite).

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:

```python title=".aspect/config.axl" theme={null}
load("@aspect//feature/console.axl", "Console")

def config(ctx: ConfigContext):
    ctx.features[Console].args.templates = {
        "banner": "",
        "header": "{% if not buildkite %}▶ {% endif %}{{ task.path }}",
        "phase": "{% if not buildkite %}» {% endif %}{{ title }}",
        "progress": "",
        "verdict": (
            "{% if not buildkite %}■ {% endif %}{{ verdict | upper }} {{ task.path }}{{ timing }}" +
            "{% if conclusion %} — {{ conclusion }}{% endif %}" +
            "{% for p in phases if p.name != 'init' %}\n    {{ p.title }} {{ p.duration }}{% endfor %}"
        ),
    }
```

```
▶ test
» Setup
» Test
■ FAILED test in 4.1s — 2 of 40 tests failed
    Setup 2ms
    Test 4.0s
```

When you start from a built-in layout instead, these are the `full` templates:

```jinja theme={null}
banner:   {{ line }}\n\n

header:   {{ ':aspect:' if buildkite else '→ 🎬' }} {{ highlight_style }}Running{{ highlight_reset }} {{ label }}

phase:    {% if not buildkite %}\n→ {{ highlight_style }}{% endif %}{% if emoji or buildkite %}{{ emoji or ':aspect:' }} {% endif %}{% if buildkite %}{{ highlight_style }}{% endif %}{{ title }}{{ highlight_reset }}{% if text %} · {{ text }}{% endif %}

progress: → {% if title %}{{ highlight_style }}{% if emoji %}{{ emoji }} {% endif %}{{ title }}{{ highlight_reset }} · {% endif %}{{ text }}

verdict:  {% if not buildkite %}\n→ {% endif %}{{ shortcode if buildkite else glyph }} {{ highlight_style }}{{ verb }}{{ highlight_reset }} {% if buildkite %}· {% endif %}{{ label }}{{ exit }}{{ timing }}{% if conclusion %} · {{ conclusion }}{% endif %}{{ breakdown }}

section:  {% if icon %}{{ icon }} {% endif %}{{ title }}
```

`\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.

> [!NOTE]
>
> 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:

```
--- :aspect: Running unit-tests [test]
--- 🧪 Test · Spawning bazel test
^^^ +++
+++ :x: Failed · unit-tests [test] (exit code 3) in 4.1s · 2 of 40 tests failed
```

The `^^^ +++` 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 `full` text if the preset leaves the slot blank too. That is why `compact` and `silent` still show phase sections and the failing-phase expansion on Buildkite.

Progress lines and the banner are ordinary lines on Buildkite, so a blank template drops them there too. Use `buildkite` in a template to print differently there:

```python theme={null}
"header": "{% if not buildkite %}→ {% endif %}Running {{ label }}",
```

## When a template is wrong

Aspect checks your templates when it reads `config.axl`, before the task starts:

| Problem | What happens |
| - | - |
| A template that doesn't compile | The run fails with the slot's path, such as `task_templates["lint"]["verdict"] does not compile` |
| A misspelled slot name | The run fails with the list of valid slots |
| A dict in `templates`, such as `{"lint": {...}}` | The run fails, printing the `task_templates` to use instead |
| A slot name as a task key, such as `task_presets = {"verdict": ...}` | The run fails: the key names no task |
| An unknown name in `task_presets` | The run fails with the list of presets |
| An entry for a task the repository doesn't define | Ignored |

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, read `ctx.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:

```python title=".aspect/my_task.axl" theme={null}
def _impl(ctx: TaskContext) -> int:
    line = ctx.console.render("progress", text = "Indexing sources")
    if line:
        print(line)
    return 0
```

`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](https://aspect.build/docs/cli/guides/status-surfaces.md) — the same preset and template model for GitHub checks, PR comments, GitLab and Buildkite annotations.
* [Built-in features reference](https://aspect.build/docs/cli/reference/features.md#console) — every `Console` option and its flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.