Quickstart - Aspect Build

The Aspect CLI (aspect) is a free, Apache-licensed task runner on top of Bazel. It replaces the shell scripts and CI YAML a Bazel monorepo accumulates (format pre-submits, lint enforcement, BUILD file generation, release delivery) with one tool that behaves the same on a laptop and in CI. Built-in tasks like aspect build and aspect test work out of the box, and custom tasks are Starlark functions you add to your repo and run as aspect <name>. The CLI needs no account. Step 4 connects to Aspect Cloud, which needs a free account. Your existing bazel workflow keeps working alongside all of it.

1. Install the CLI

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

Works on macOS and Linux, with no extra package manager. The script installs the aspect-launcher binary as /usr/local/bin/aspect, using sudo, so it may prompt for your password. The launcher is a thin shim that downloads and runs the actual CLI, like bazelisk for Bazel, or nvm for Node. See Install the Aspect CLI for other installation methods (Homebrew, GitHub Actions, bazel_env, manual download). Verify the install:

aspect --version    # prints the launcher's own version

The launcher runs whichever CLI version your repository pins, which step 3 sets.

2. Point `aspect` at a Bazel repo

I already use Bazel
I'm new to Bazel

aspect build, aspect test, and aspect run work in any existing Bazel workspace. cd into your repo and try them out:

aspect build //...
aspect test //...

# Or scope to a specific target pattern
aspect build //path/to/package/...
aspect test //path/to/package:my_test

# Run a binary target
aspect run //path/to/package:my_binary

The rest of the quickstart works against your existing MODULE.bazel or WORKSPACE.

You’ll need bazel on your PATH alongside aspect. The recommended way is Bazelisk, a launcher that reads .bazelversion from your repo and downloads the matching Bazel, same idea as the aspect launcher.

# macOS (Homebrew)
brew install bazelisk

# Linux (download a release binary)
curl -fsSL -o /usr/local/bin/bazel \
  https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
chmod +x /usr/local/bin/bazel

Verify:

bazel --version

Now create a tiny Bazel repo to play with:

mkdir hello && cd hello
cat > MODULE.bazel <<'EOF'
module(name = "hello", version = "0.0.0")
bazel_dep(name = "rules_shell", version = "0.8.0")
EOF
cat > BUILD.bazel <<'EOF'
load("@rules_shell//shell:sh_binary.bzl", "sh_binary")
load("@rules_shell//shell:sh_test.bzl", "sh_test")

sh_binary(name = "hello", srcs = ["hello.sh"])
sh_test(name = "hello_test", srcs = ["hello_test.sh"])
EOF
cat > hello.sh <<'EOF'
#!/usr/bin/env bash
echo "hello, aspect!"
EOF
cat > hello_test.sh <<'EOF'
#!/usr/bin/env bash
[ "$(echo hi)" = "hi" ] && echo "ok"
EOF
chmod +x hello.sh hello_test.sh

Now run the three core tasks:

aspect build //...
aspect test //...
aspect run //:hello

Each invocation runs the equivalent bazel command, with the same flags and the same exit code, and adds:

A status line summarizing the task and its phases (🔨 Build, 🧪 Test, 🚀 Run)
Automatic retry on transient Bazel errors (BLAZE_INTERNAL_ERROR, LOCAL_ENVIRONMENTAL_ERROR)
A consistent task lifecycle that CI integrations hook into (status checks, annotations, artifact upload)

3. Pin the CLI version

For reproducible builds across developers and CI, pin the CLI version in your repo. Connecting to Aspect Cloud in the next step needs v2026.41.24 or newer:

.aspect/version.axl

version("2026.41.50")

The launcher reads this file and downloads the matching aspect-cli binary the first time it’s needed, then caches it. See Pin the Aspect CLI version for custom sources (local builds, internal mirrors, alternate registries).

4. Connect to Aspect Cloud

A remote cache means an action that has already run with the same inputs, platform and configuration comes back from the cache instead of running again. Sign up for an Aspect account. The Free tier needs no credit card to start; see pricing for its limits. Then log in:

aspect auth login

That opens a browser, signs you in, and stores the credential in your OS keyring (the macOS Keychain, or the Linux kernel keyring). Aspect Cloud’s endpoints are built into the CLI, so there’s nothing else to configure.

With aspect
With vanilla bazel

Add --remote to any task:

aspect build //... --remote

It connects the build to the remote cache and streams it to the Build Results UI. Off CI, a task builds locally unless you pass the flag, so you choose when to use the cache.

Write a Bazel rc that declares Aspect Cloud’s flags:

aspect setup bazelrc

That writes .aspect/bazelrc and a try-import at the top of your .bazelrc; commit both. The file turns nothing on by itself, so opt a build in by name:

bazel build //... --config=aspect-cloud

Bazel authenticates through aspect as a credential helper, so keep aspect on your PATH.

Now clear your local outputs and build again, so nothing can come from your own machine:

bazel clean
aspect build //... --remote

This time the actions should come back as remote cache hit. The CLI prints a link to the invocation in the Build Results UI, which shows the cache hit rate. aspect cache diff names any actions that missed. Aspect Cloud local setup covers profiles, organizations, making the cache the default, and checking it all worked. Give CI jobs the same cache as your laptop.

Create an API token on the app’s API tokens settings page. Copy it when it’s displayed: it’s shown only once.
Store it as a CI secret named ASPECT_API_TOKEN.
Install the Aspect Workflows GitHub App (optional, for PR status checks and comments) on your GitHub org, and link it to your Aspect account. See GitHub App.

On GitHub Actions, hand the token to the setup-aspect action:

.github/workflows/ci.yaml

permissions:
  contents: read
  id-token: write    # artifact uploads and the PR summary comment

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: |
          aspect build //...
          aspect test //...

The action installs the launcher and Bazelisk, logs in with the token, and points vanilla bazel at the same cache, so bazel steps get it too. On CI, a task uses the cache without --remote. Aspect Cloud CI setup covers Buildkite, CircleCI, GitLab CI and any other CI, and the setup step’s inputs. Running tasks in CI has complete pipeline examples for the Aspect CLI tasks.

Go further with the CLI

Discover what’s available

aspect help

The output lists every task the CLI knows about, including any you’ve defined in this repo. The built-in set:

Command	What it does
`aspect build`	Build Bazel targets
`aspect test`	Run Bazel tests with optional LCOV coverage
`aspect run`	Build and run a binary target
`aspect format`	Format only the files changed in the PR
`aspect lint`	Run linters with hold-the-line strategy
`aspect gazelle`	Generate and sync BUILD files
`aspect delivery`	Deliver only targets whose outputs changed (selective mode needs Workflows CI runners)

aspect <task> --help shows every flag for a specific task with its current default.

Customize tasks in `config.axl`

Built-in tasks accept configuration via .aspect/config.axl at the repo root. The file is evaluated once per invocation, locally and in CI. This config activates a --config=ci group from your .bazelrc when the CI env var is set, and turns on test-log artifact upload for failures:

.aspect/config.axl

load("@aspect//traits.axl", "BazelTrait")
load("@aspect//feature/artifacts.axl", "ArtifactUpload")

def config(ctx: ConfigContext):
    if bool(ctx.std.env.var("CI")):
        ctx.traits[BazelTrait].extra_flags.extend(["--config=ci"])

    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"

BazelTrait.extra_flags land in Bazel’s build rc section, so they reach every build-like invocation the CLI makes — build, test, run, coverage — but not bazel query, which keeps a build-only flag from breaking a task’s sidecar query. ArtifactUpload uploads test logs, BEP, Bazel profiles, and execution logs to your CI platform’s native artifact storage. Both are documented in aspect build & aspect test.

Write your first custom task

When the built-ins don’t cover what you need, write your own. Custom tasks are Starlark functions you register with the task() built-in. Drop them in any .axl file inside .aspect/ and they’re auto-discovered as CLI commands (see How tasks are registered for the other registration paths):

.aspect/build-and-list.axl

def _impl(ctx: TaskContext) -> int:
    events = bazel.build_events.iterator(kinds = ["named_set_of_files"])
    build = ctx.bazel.build(
        build_events = [events],
        *ctx.args.targets,
    )

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

    return build.wait().code

build_and_list = task(
    summary = "Build targets and list every output file.",
    implementation = _impl,
    args = {
        "targets": args.positional(default = ["..."], maximum = 512),
    },
)

Re-run aspect help and your new build-and-list task appears alongside the built-ins (the variable name’s underscores become dashes in the command):

aspect build-and-list //...
# Built hello.sh
# Built hello
# Built hello_test.sh
# Built hello_test

Tasks can call any subprocess, read and write files, query the build graph, subscribe to Bazel’s Build Event Stream and its execution log for detail on individual actions, and define their own typed arguments. See Run and define tasks for the full walkthrough.

Where to next

Speed up more of your builds

Aspect Cloud CI setup: the same cache for vanilla bazel steps on the CI runners you already have.
Aspect Workflows: remote execution and warm CI runners, and when you’d want Aspect Enterprise, an isolated deployment of your own.

More on the CLI

Tasks overview: every built-in task, with config options and CI examples.
Run and define tasks: writing custom tasks, with arguments, processes, the filesystem, build queries, phases and cleanup.
External AXL modules: extension libraries like rules_lint, pulled in through MODULE.aspect.
AXL reference: every type, function and module AXL exposes.

​1. Install the CLI

​2. Point aspect at a Bazel repo

​3. Pin the CLI version

​4. Connect to Aspect Cloud

​5. Share the cache with CI

​Go further with the CLI

​Discover what’s available

​Customize tasks in config.axl

​Write your first custom task

​Where to next