Run and define tasks - Aspect Build

The Aspect CLI ships with built-in tasks (build, test, format, lint, etc.) and lets you define your own in AXL. After installing, run aspect help to see what’s available:

% aspect help
Aspect CLI v2026.41.50 — https://aspect.build/docs/cli

Aspect's programmable task runner built on top of Bazel
{ Correct, Fast, Usable } -- Choose three

Usage: aspect [TASK|GROUP|COMMAND]

Tasks:
  build         Build Bazel targets. Wraps `bazel build` with retries, remote cache/BES wiring, and CI status reporting.
  delivery      Build and deliver binary targets. Targets are built with stamping and delivered exactly once per commit unless forced; change detection skips targets whose outputs haven't changed since the last delivery.
  format        Format source files with the configured formatter target. Formats changed files by default; `--scope=all` for the whole tree.
  gazelle       Generate and update BUILD files with gazelle. Applies the patch locally; detect-only on CI (`--check-only`).
  gc            Reclaim Bazel output bases and download-cache entries nothing is using.
  init          Scaffold a new Bazel project from the Aspect Workflows template.
  lint          Lint targets using rules_lint aspects and report findings on the terminal or as code-review comments.
  mcp           Serve build results to AI agents over MCP
  output-bases  List the Bazel output bases on this machine: state, Bazel server memory, git branch, workspace and size.
  run           Build a target with bazel and run the resulting binary.
  test          Run Bazel tests. Wraps `bazel test` with retries, remote cache/BES wiring, and CI status reporting.

Task Groups:
  auth      configure, login, logout, remove, status, use
  axl       add
  cache     diff
  ci        bazelrc, runner-health-check, runner-metadata, warming
  github    token
  setup     bazelrc, tools-bazel-wrapper, workspace-data
  worktree  add, inspect, list, path, prune, release

Commands:
  describe  Print the resolved task, flag and feature surface as JSON
  feature   List features and their flags
  version   Print version
  help      Print this message or the help of the given subcommand(s)

Options:
  -v, --version  Print version
  -h, --help     Print help

Built-in tasks like build and test are loaded from the @aspect extension library. Custom tasks you define locally appear alongside them. The root help carries only --version and --help. The --task:* flags every task accepts live in a Task Options: block on the task’s own help — aspect build --help.

How tasks are registered

A task becomes an aspect <name> CLI command in one of these ways.

1. Auto-discovery in `.aspect/`

The CLI scans every .axl file inside an .aspect/ directory and registers any task(...) it finds at the module’s top level. The scan starts in your current working directory and walks up to the workspace root, so subdirectories can scope tasks to themselves:

.
├── .aspect/
│   ├── config.axl
│   ├── version.axl
│   └── mycmd.axl      # 'mycmd' task, available everywhere
├── app1/
│   └── .aspect/
│       └── subcmd.axl # 'subcmd' task, scoped to app1
├── MODULE.aspect
└── MODULE.bazel

From inside app1, the CLI loads tasks from app1/.aspect/, then walks up and loads tasks from the root .aspect/. Both mycmd and subcmd are visible. From the repo root, only mycmd is.

config.axl and version.axl are reserved filenames inside .aspect/. The task auto-discovery scan skips them; they’re loaded for their own purpose (CLI / task configuration and version pinning, respectively). Tasks defined directly in those files won’t appear as CLI commands; use a separately-named .axl file or the programmatic path below.

2. External AXL modules via `MODULE.aspect`

Tasks shipped by an external AXL module are pulled in by declaring the module in MODULE.aspect at the repo root. With auto_use_tasks = True, every task the module exports becomes a CLI command without a load() in your own files; otherwise you load() the symbols you want. See Use external AXL modules for the full mechanics.

3. Programmatic registration in `config.axl`

config.axl itself isn’t scanned for top-level tasks, but it can register them programmatically, which is useful when the task value comes from a helper or an alias rather than a static task(...) literal. The canonical example is format.alias(), which produces a task value you register with ctx.tasks.add(...):

.aspect/config.axl

load("@aspect//format.axl", "format")

buildifier = format.alias(
    defaults = {
        "formatter_target": "@buildifier_prebuilt//buildifier",
        "formatter_args_for_tree_walk": ["-r", "."],
        "run_in": "cwd",
        "include_patterns": [
            "**/BUILD",
            "**/BUILD.bazel",
            "**/MODULE.bazel",
            "**/*.MODULE.bazel",
            "**/WORKSPACE",
            "**/WORKSPACE.bazel",
            "**/*.axl",
            "**/*.bzl",
        ],
    },
    summary = "Format Starlark files using buildifier.",
)

def config(ctx: ConfigContext):
    ctx.tasks.add(buildifier)

After this runs, aspect buildifier is a real CLI command alongside the built-ins. See aspect buildifier for the complete alias.

Config file precedence

config.axl files are evaluated in a fixed order. Later files override values set by earlier ones, and an explicit CLI flag always beats any config value:

The project root’s .aspect/config.axl.
Any nested .aspect/config.axl files walking down from the project root toward the current working directory.
The user-global ~/.aspect/config.axl, if the file exists.
Explicit CLI flags (--flag=value).

User-global `~/.aspect/config.axl`

Use ~/.aspect/config.axl for per-machine, per-user preferences that apply across every Aspect project. Common cases: defaulting --config=debug, opting a workstation into an internal build cache, or setting a personal task:friendly-name. It loads after every project config, so your overrides win over repo defaults. To force a value regardless of any config, pass it as a CLI flag. The file is optional. If it doesn’t exist, discovery is unchanged. If a project’s root happens to be your home directory, the file is loaded once, not twice. ~/.aspect/config.axl evaluates in its own module scope rooted at ~/.aspect, independent of the project. Both relative (./helpers.axl) and module-rooted (helpers.axl) load() statements resolve inside ~/.aspect. Any load() that would escape that directory fails with a confinement error. Split helpers into sibling files under ~/.aspect/ and load them from config.axl:

~/.aspect/config.axl

load("./helpers.axl", "apply_personal_defaults")

def config(ctx: ConfigContext):
    apply_personal_defaults(ctx)

Write your first extension

Custom tasks are Starlark functions registered with the task() built-in. To create a mycmd task that builds targets and prints each output file path:

Create a .aspect directory at the root of your project:
mkdir .aspect
Create a file named mycmd.axl within the .aspect directory:
touch .aspect/mycmd.axl

Add the following Starlark code to mycmd.axl:

def impl(ctx: TaskContext) -> int:
    events = bazel.build_events.iterator()
    build = ctx.bazel.build(
        build_events = [events],
        *ctx.args.target_pattern,
    )

    for event in events:
        if event.kind == "named_set_of_files":
            for f in event.payload.files:
                ctx.std.io.stdout.write("Built {}\n".format(f.name))

    return build.wait().code

mycmd = task(
    implementation = impl,
    summary = "Build targets and print each output file path.",
    args = {
        "target_pattern": args.positional(default = ["..."], maximum = 512),
    },
)

Verify the new task appears:

% aspect help
...
Tasks:
  build     Build Bazel targets. Wraps `bazel build` with retries, remote cache/BES wiring, and CI status reporting.
  ...
  mycmd     Build targets and print each output file path.
  ...

Test the new AXL task by running:
aspect mycmd //...

Task arguments

The args dict in task() maps argument names to arg specs. Argument names become kebab-case CLI flags (output_dir → --output-dir). Values merge from defaults → project config.axl overrides → user-global ~/.aspect/config.axl overrides → CLI flags, with CLI winning. See Config file precedence for the full order.

Constructor	CLI form	Type in `ctx.args`
`args.string(default="")`	`--flag=value`	`str`
`args.boolean(default=False)`	`--flag` / `--flag=false`	`bool`
`args.int(default=0)`	`--flag=42`	`int`
`args.uint(default=0)`	`--flag=42`, non-negative	`int`
`args.string_list(default=[])`	`--flag=a --flag=b`	`list[str]`
`args.boolean_list()`, `args.int_list()`, `args.uint_list()`	the flag repeated, one value each	`list[bool]`, `list[int]`
`args.positional(default=[], minimum=0, maximum=1)`	positional words; `maximum` defaults to 1, so pass `maximum = 512` to accept a list of target patterns	`list[str]`
`args.trailing_var_args()`	everything after the known arguments, unparsed; one per task, last	`list[str]`
`args.passthrough(position="post_command")`	flags the task doesn’t declare, collected instead of rejected; `"pre_command"` collects those before the task name	`list[str]`, read with `ctx.args.claim(name)`
`args.custom(type, default=None)`	config.axl only, not exposed on the CLI	`type`

Use values=["a","b","c"] on args.string to restrict to a fixed set. The CLI validates the input and shows choices in --help. Any scalar arg accepts short="x" for a single-character alias (e.g., -v). Here’s a task that generates code from Bazel targets using typed arguments:

def _impl(ctx: TaskContext) -> int:
    for target in ctx.args.targets:
        result = (ctx.std.process.command("codegen")
            .args(["--lang", ctx.args.lang, "--", target])
            .spawn()
            .wait())
        if not result.success:
            return result.code
    return 0

gen = task(
    implementation = _impl,
    summary = "Run the code generator on Bazel targets.",
    args = {
        "lang": args.string(
            default = "go",
            values = ["go", "typescript", "python"],
            description = "Output language.",
        ),
        "verbose": args.boolean(default = False, short = "v"),
        "targets": args.positional(default = ["//..."], maximum = 512),
    },
)

aspect gen --lang=typescript //services/...
aspect gen -v //...

Tasks are named from their variable name converted to kebab-case: my_cmd → my-cmd. The task() built-in also accepts summary (one-liner in aspect help), description (extended --help text), kind (overrides the derived name, and sets the task kind that status surfaces and CI task names key on), and group (nests the command — group = ["tools"] gives aspect tools my-cmd).

Always set `summary`

summary is strongly recommended on every task() and is slated to become required in a future release. A task without one renders in aspect --help as the placeholder "<kind> task defined in <file>". That’s the level at which readers choose a task, so an undocumented task is effectively invisible. To make that gap visible today, aspect prints a deprecation warning on stderr for each first-party task defined without a summary, naming the kind and defining file:

WARNING: task "deploy" in .aspect/deploy.axl has no summary, so it shows as
"deploy task defined in .aspect/deploy.axl" in `aspect --help`. Add
summary = "…" to task(...) — this becomes an error in a future release.

The warning is scoped to tasks defined in the current repo. Tasks pulled in from an external AXL module (whose defining label starts with @mod//…) don’t warn, since they’re the module author’s to fix, not yours. Silence the warning by adding a one-line summary to each task(...) call it names.

Running processes

Use ctx.std.process.command(binary) to run any tool. .spawn() is non-blocking and returns a handle; .wait() blocks until the process exits.

result = (ctx.std.process.command("gofmt")
    .args(["-w", "."])
    .spawn()
    .wait())

if not result.success:
    return result.code

Capture stdout with .stdout("piped"):

result = (ctx.std.process.command("git")
    .args(["log", "--oneline", "-5"])
    .stdout("piped")
    .spawn()
    .wait_with_output())

ctx.std.io.stdout.write(result.stdout)
return result.status.code

.current_dir(path) sets the working directory. .env(name, value) injects an environment variable. Methods chain: each returns the same Command.

File and environment access

Filesystem: ctx.std.fs reads and writes files:

root = ctx.std.env.aspect_root_dir()

if ctx.std.fs.exists(root + "/codegen.json"):
    config = ctx.std.fs.read_to_string(root + "/codegen.json")

ctx.std.fs.write("/tmp/output.txt", "done\n")

Environment: ctx.std.env inspects the runtime environment:

Method	Returns
`ctx.std.env.var("NAME")`	Env var value, or `None` if unset
`ctx.std.env.current_dir()`	Current working directory
`ctx.std.env.aspect_root_dir()`	Aspect project root: the nearest directory with `.aspect/version.axl` or `MODULE.aspect`, else the Bazel workspace root, else the current directory
`ctx.std.env.bazel_root_dir()`	Bazel workspace root: the nearest directory with `MODULE.bazel` or `WORKSPACE`. Differs from `aspect_root_dir()` when a Bazel sub-workspace sits under an Aspect root
`ctx.std.env.git_root_dir()`	Git repository root, or `None` outside a git repository
`ctx.std.env.temp_dir()`	System temp directory

A common pattern is branching on whether the task is running in CI. ctx.std.env.var() works the same in both TaskContext (task implementations) and ConfigContext (config.axl):

is_ci = bool(ctx.std.env.var("CI"))
if is_ci:
    # CI-only behaviour
    pass

Rich return values

Tasks return an int exit code or a TaskConclusion for a message alongside the exit code. The message appears in the terminal and in CI platform annotations.

def _impl(ctx: TaskContext) -> int | TaskConclusion:
    status = ctx.bazel.build("//...").wait()
    if status.code != 0:
        return TaskConclusion(
            exit_code = status.code,
            text = "Build failed. Run 'aspect build //...' locally to reproduce.",
        )
    return 0

text is the short suffix on the closing bookend. For a refusal whose explanation is the whole story, pass message instead: it prints on its own line before the bookend, as an ERROR: line for a non-zero exit code, with no traceback.

def _impl(ctx: TaskContext) -> int | TaskConclusion:
    if not ctx.args.targets:
        return TaskConclusion(exit_code = 1, message = "Provide a target, e.g. `aspect build //...`.")
    ...

From a nested helper, where a return can’t reach the task, ctx.std.process.exit(code, message) ends the task the same way. So does raising an error whose type was declared with traceback = False, which exits with code 1 (see Errors and error handling). Keep a plain fail("...") for bugs, where the traceback is what you want.

Errors and error handling

An error in AXL is a value. error("message") builds one, and error.type(...) derives a new error type with its own fields. Every error has a message, a cause (the error that led to it, or None), and a stacktrace. Declare error types at module top level. A type takes its name from the variable it is first assigned to, and that name appears in repr(e) and tracebacks. Fields take a type, or field(type, default = ...) for an optional field:

DeployError = error.type(fields = {
    "deployment": str,
    "attempt": field(int, default = 1),
})
DeployTimeout = DeployError.type(fields = {"after_ms": int})
NotLoggedIn = error.type(traceback = False)

A derived type inherits its parent’s fields, and isinstance(e, DeployError) is true for a DeployTimeout. isinstance(e, error) is true for every error. Raising. fail(e) raises the error value itself, keeping its type, fields, cause, and stacktrace:

def _deploy(ctx, target, previous):
    ...
    fail(DeployTimeout("no ack", deployment = target, after_ms = 30000, cause = previous))

The type’s traceback setting decides how an escaping error renders. With traceback = True (the default), Aspect CLI prints the traceback and TypeName: message. Use it for failures someone has to debug. With traceback = False, Aspect CLI prints only the message as an ERROR: line and exits with code 1, as ctx.std.process.exit(1, message) would. Use it for expected refusals, like a missing login. A derived type inherits its parent’s setting unless it sets its own. Catching. catch turns a failure into a value in one of two forms. Both return an (err, value) pair: (None, value) on success, (err, None) on failure. Test if err: before using value.

# On a future: call catch() right before block().
err, resp = ctx.http().get(url = url).catch().block()
if err:
    ctx.std.io.stderr.write("upload skipped: " + err.message + "\n")
    return 0

# Around any call: catch(function, *args, types = [...], **kwargs) makes the call for you.
err, config = catch(_load_config, ctx, path, types = [ConfigError])
if err:
    config = DEFAULT_CONFIG

Name the types you expect. fut.catch(DeployError) and catch(fn, types = [DeployError]) catch only those types and their subtypes. Any other failure still raises. A bare catch() catches every failure, including bugs raised with a plain fail.
Re-raise with fail(err). A caught error keeps its type and fields.
Exits are not caught. ctx.std.process.exit inside the caught code still ends the task. A raised error with traceback = False is caught like any other error.
Failures that are not error values arrive as a plain error, with the failure text as message.
fut.catch() must be the last call before block(), and you can call it only once.

Futures are typed with what they resolve to, for example Future[HttpResponse]. So catch().block() returns tuple[error | None, HttpResponse | None]. See Future.catch and error for the full API.

Cleanup with defer

ctx.defer(callable, *args) registers a cleanup function that runs after the task returns, in LIFO order, even on failure or cancellation. A deferred call that fails is reported as a WARNING: line and doesn’t change the exit code. The pattern is borrowed from Go’s defer.

def _impl(ctx: TaskContext) -> int:
    log = ctx.std.fs.create("/tmp/build.log")
    ctx.defer(log.flush)  # flushed even if impl exits early

    build = ctx.bazel.build("//...", stdout=log)
    return build.wait().code

Use ctx.defer for any resource that must be cleaned up regardless of how the task exits: file handles, temp files, running subprocesses. When the cleanup or follow-up depends on how the task ended, register a post-task hook instead; see Run code before and after a task.

Querying the build graph

ctx.bazel.query(expr) runs bazel query and returns an iterable of targets that supports len() and indexing:

def _impl(ctx: TaskContext) -> int:
    targets = ctx.bazel.query("kind('container_push rule', //services/...)")

    for target in targets:
        ctx.std.io.stdout.write(target.name + "\n")
    return 0

Any Bazel query expression works: deps(), rdeps(), kind(), attr(), somepath(), set operations, and so on. Pass flags = [...] for extra query flags:

results = ctx.bazel.query("deps(//myapp:main) intersect kind('go_library rule', //...)")

For Bazel server information, ctx.bazel.info() returns a dict of every key Bazel exposes (output_base, execution_root, workspace, release, etc.):

info = ctx.bazel.info()
log_dir = info["output_base"] + "/external"

Task identity and phases

ctx.task describes the currently-running task. Use it to log identifiers that show up in CI annotations, or to break long-running work into named phases that surface in status displays:

def _impl(ctx: TaskContext) -> int:
    ctx.std.io.stdout.write("Run {}\n".format(ctx.task.id))

    ctx.task.phase("build", description = "Building deliverables")
    build_status = ctx.bazel.build("//...").wait()
    if build_status.code != 0:
        return build_status.code

    ctx.task.phase("test", description = "Running tests")
    return ctx.bazel.test("//...").wait().code

Available fields:

Field	Description
`ctx.task.kind`	Task kind: the command being run (e.g. `"build"`, `"test"`, `"my-cmd"`)
`ctx.task.friendly_kind`	Human-readable label for the kind, from `task(friendly_kind=...)` (defaults to a Title-Cased kind, e.g. `"Build"`)
`ctx.task.name`	Unique name for this invocation, from `--task:name` (auto-generated when unset: from the CI job name on CI, else `<kind>-<random-suffix>`)
`ctx.task.friendly_name`	Human-readable label for the invocation, from `--task:friendly-name` (defaults to the name)
`ctx.task.id`	UUID v4 unique per invocation
`ctx.task.elapsed_ms`	Wall time in milliseconds since the task spawned

ctx.task.phase(name, description="", emoji="", display_name="") marks the start of a new phase. The currently-active phase closes automatically when the next one starts or when the task returns.

​How tasks are registered

​1. Auto-discovery in .aspect/

​2. External AXL modules via MODULE.aspect

​3. Programmatic registration in config.axl

​Config file precedence

​User-global ~/.aspect/config.axl

​Write your first extension

​Task arguments

​Always set summary

​Running processes

​File and environment access

​Rich return values

​Errors and error handling

​Cleanup with defer

​Querying the build graph

​Task identity and phases

How tasks are registered

1. Auto-discovery in `.aspect/`

2. External AXL modules via `MODULE.aspect`

3. Programmatic registration in `config.axl`

Config file precedence

User-global `~/.aspect/config.axl`

Write your first extension

Task arguments

Always set `summary`

Running processes

File and environment access

Rich return values

Errors and error handling

Cleanup with defer

Querying the build graph

Task identity and phases