Skip to main content

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.

Aspect CLI ships built-in tasks — aspect build, aspect test, aspect run, aspect format, aspect lint, aspect delivery, aspect gazelle, plus aspect buildifier as a one-liner you opt into — that run on any CI system. Built-in tasks work out of the box; customize their behavior in .aspect/config.axl. Extend the CLI with your own tasks by dropping .axl files into .aspect/ — they’re auto-discovered. Invoke any task with aspect <task> in your CI YAML and it works the same whether the pipeline runs on GitHub Actions, Buildkite, GitLab, CircleCI, a self-hosted runner, or your local machine. On Aspect Workflows self-hosted runners, tasks automatically detect the environment and configure remote caching, remote build execution, and pre-warmed NVMe output bases — no extra setup required.
Run aspect help from inside your repo to list every task available (built-ins plus any custom ones). For per-task help, aspect <task> --help shows all flags with their defaults.

​
Task reference

CLI commandWhat it doesGuide
aspect buildBuild Bazel targetsaspect build & test
aspect testRun Bazel testsaspect build & test
aspect runBuild and run a binary targetaspect run
aspect formatFormat source filesaspect format
aspect buildifierFormat Starlark files (opt-in via format.alias())aspect buildifier
aspect lintRun lintersaspect lint
aspect gazelleGenerate and sync BUILD filesaspect gazelle
aspect deliveryDeliver build artifactsaspect delivery

​
Configuration

.aspect/config.axl at the root of your repository is the central place to customize tasks and wire up task hooks. It is evaluated once per aspect <task> invocation; values can branch on environment variables, CLI flags, or any Starlark expression. A minimal config enabling artifact uploads for CI:
.aspect/config.axl
load("@aspect//feature/artifacts.axl", "ArtifactUpload")
load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))

    if is_ci:
        ctx.traits[BazelTrait].extra_flags.extend([
            "--config=ci",
        ])

    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"
    ctx.features[ArtifactUpload].args.upload_profile = True
See Running tasks in CI for complete CI YAML for all four supported providers.

​
Running tasks in CI

The same aspect <task> command runs identically in CI and on a developer machine — no wrapper scripts, no CI-specific flags. The CLI reads the CI environment variable to activate CI-specific behaviors (remote cache usage, artifact upload, status checks). Minimal CI example (GitHub Actions): 
- uses: actions/checkout@v6
- run: aspect build //...
- run: aspect test //...
Set ASPECT_API_TOKEN in the job environment to unlock GitHub Status Checks, Buildkite Annotations, and GitLab job annotations. Without it, tasks still build and test normally. See Running tasks in CI for platform-specific pipeline YAML.

​
Version pinning

Pin the CLI version in .aspect/version.axl to ensure reproducible behavior: 
version("2026.22.39") # minimum for all built-in tasks
See version pinning for the full set of source options.