3.5.4 Aspect CLI Extensibility

Vanilla Bazel deliberately concentrates on the build graph. Repositories still need repeatable commands for formatting, linting, BUILD-file generation, delivery, and CI reporting. Aspect CLI (aspect-build/aspect-cli) is a programmable task runner on top of Bazel that gives those workflows one command surface without replacing the bazel executable.¹

Install and pin it

Install the open-source CLI on macOS or Linux with the upstream installer:¹

curl -fsSL https://install.aspect.build | bash
aspect help

The executable is named aspect and works alongside bazel. Check in .aspect/version.axl to pin the repository's CLI version. The launcher fetches that version on first use, keeping laptops and CI aligned.¹ Treat the pin like .bazelversion: review upgrades, land the version change, then let each environment resolve the checked-in choice.

For a concrete route through the current implementation, the Aspect CLI repository map starts at the supported README contract, then narrows to focused AXL fixtures such as examples/cache-diff/. That example demonstrates an execution-log-driven task. It does not require every AXL task to consume execution logs.²

Three built-in tasks work in any Bazel workspace without additional graph wiring:¹

aspect build //...
aspect test //...
aspect run //app

aspect help lists both built-in and repository-defined tasks. Other built-ins, including format, lint, gazelle, and delivery, need repository setup: a pinned tool in MODULE.bazel, a BUILD target or rule that exposes it, and AXL configuration in .aspect/config.axl.¹ Installing the CLI alone does not make aspect lint know which linters your graph uses.

Extend it with AXL

The current extension model is AXL, the Aspect Extension Language. Built-in tasks are configured in .aspect/config.axl. A custom .aspect/*.axl file becomes a project command. A small task can call Bazel and return its exit code:¹

# .aspect/codegen.axl
def _impl(ctx: TaskContext) -> int:
    return ctx.bazel.build(*ctx.args.targets).wait().code

codegen = task(
    summary = "Run the code generator.",
    implementation = _impl,
    args = {
        "targets": args.positional(default = ["//gen/..."]),
    },
)

The checked-in task is then available locally and in CI:

aspect codegen //gen/services/...

AXL tasks can run subprocesses, read or update repository files, query the graph, and subscribe to the Build Event Stream or compact execution log.¹ 3.7.3 Aspect Extension Language (AXL) develops that orchestration model. The decision here is whether the repository benefits from adopting Aspect CLI as its shared task surface.

Keep the launcher layers distinct

• Bazelisk (0.1.1 Bazelisk & .bazelversion) selects and downloads the Bazel version named by the repository.
• tools/bazel (3.2.8 tools/bazel Wrapper) is a thin pre-Bazel setup hook for environment stabilization and policy.
• Aspect CLI runs project tasks around Bazel and is invoked as aspect.
• AXL (3.7.3 Aspect Extension Language (AXL)) is the language used to configure and author those tasks.

This separation makes adoption reversible. Existing bazel build and bazel test commands remain valid, while selected human and CI workflows move to aspect <task> when its reporting, retries, or orchestration justify the additional tool.

To see what aspect init currently materializes, use the aspect-workflows-template map. The template/.aspect/ directory is the delivered project configuration, while render.axl belongs to the template generator itself. Keeping those apart prevents a common mistake: editing the meta-template workflow when the task is only to maintain a generated workspace.