Quickstart

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

​

1. Install the CLI

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

aspect --version
# aspect launcher 2026.22.39

​

2. Build and test a Bazel repo

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

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

• A status line summarising 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 can hook into (status checks, annotations, artifact upload)

​

3. Discover what’s available

aspect help

​

4. Pin the CLI version

version("2026.22.39")

​

5. Customize tasks in 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"

​

6. Write your first custom task

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),
    },
)

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

​

7. Run the same tasks in CI

​

Set up ASPECT_API_TOKEN (recommended)

1. Sign up for a free Aspect account at signup.aspect.build (no credit card required).
2. Install the Aspect Workflows GitHub App on your GitHub org and link it to your Aspect account from the authentication page. The App is what lets the CLI post status checks, PR comments, and suggested fixes back to GitHub.
3. Generate an ASPECT_API_TOKEN in the API Tokens portal. The token is a <CLIENT_ID>:<SECRET> string — copy it as soon as it’s displayed (the secret half is shown only once).
4. Store the token as a CI secret on each provider you use:
   • GitHub Actions — Settings → Secrets and variables → Actions → New repository secret, named ASPECT_API_TOKEN.
   • Buildkite — store it in your secret manager and reference it from env: (your-buildkite-secret-ref in the example below).
   • GitLab CI — Settings → CI/CD → Variables → Add variable, masked, named ASPECT_API_TOKEN.
   • CircleCI — Project Settings → Environment Variables → Add Environment Variable (or a Context if you want to share across projects).

permissions:
  id-token: write

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

​

Where to next

• Tasks overview — full reference for every built-in task with config options and CI examples.
• How to run and define tasks — deep dive on writing custom tasks: arguments, processes, filesystem, build queries, phases, cleanup.
• How to use external AXL modules — pull in extension libraries like rules_lint via MODULE.aspect.
• AXL reference — every type, function, and module that AXL exposes.
• Aspect Workflows — purpose-built Bazel CI runners that detect aspect tasks automatically and apply remote cache, RBE, and pre-warmed output bases.