Install the Aspect CLI - Aspect Build

Every install method puts the aspect-launcher on your PATH as aspect. The launcher downloads and runs the Aspect CLI version configured in your repository, the way Bazelisk fetches the configured Bazel.

After installing, follow the Quickstart for a 10-minute end-to-end walkthrough: build, test, customize built-ins, and extend the CLI with your first custom task.

Install with curl

The curl script works on macOS and Linux without any prerequisite package manager. Run:

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

The script installs the aspect-launcher binary to /usr/local/bin/aspect with sudo mv, so it may prompt for your password. Pass a version to pin the launcher, as CI jobs should:

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

A pinned version downloads the release asset directly and skips the GitHub API lookup, which is rate-limited for anonymous callers. Without a version, the script queries the API for the latest release and uses GITHUB_TOKEN if it’s set.

Updating with curl

Re-run the installation script:

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

Install with Homebrew (macOS)

brew install aspect-build/aspect/aspect

Alternatively, tap the repository first and then install:

brew tap aspect-build/aspect
brew install aspect

Updating with Homebrew (macOS)

brew update
brew upgrade aspect

Install the Aspect CLI with `direnv` and `multitool`

This method assumes your development environment uses bazel_env.bzl. For examples, refer to the aspect-starters repositories on GitHub.

Add aspect to the multitool lockfile, as shown in this example.
Build and run your bazel_env target. Bazel will handle the installation of aspect, making it available on your PATH.

For more details on this pattern, watch the Aspect Insights podcast episode “Developer Tooling in Monorepos with bazel_env”:

Install with GitHub Actions

Use the aspect-build/setup-aspect action. In one step it:

installs the launcher, and Bazelisk unless bazel is already on PATH
exchanges your ASPECT_API_TOKEN for a short-lived JWT
runs aspect setup bazelrc (bazelrc-generate, on by default), so vanilla bazel calls use the remote cache and stream to the Build Results UI
caches --repository_cache through the GitHub Actions cache (on by default); --disk_cache caching is off by default (disk-cache: true to turn it on)

The same step works on provider-hosted runners (ubuntu-latest, macos-latest) and on Aspect Workflows CI runners.

permissions:
  contents: read    # actions/checkout
  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 test --task:name=test -- //...

Pin to a full-length commit SHA (with the version annotated in a trailing comment) per GitHub’s third-party action security guidance. Find the SHA for the latest release on the setup-aspect releases page; each release’s notes carry a copy-paste snippet. The CLI version itself is pinned by your repo’s .aspect/version.axl (see version pinning). The launcher reads that file and downloads the matching CLI on first aspect invocation, so local and CI stay in sync without bumping a launcher version in your workflow YAML.

Without `setup-aspect`

To install the launcher inline instead, use the curl script with a pinned version. Buildkite, GitLab, and CircleCI have their own integrations; see CI setup.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Aspect CLI
        run: curl -fsSL https://install.aspect.build | bash -s -- 2026.39.10
      - name: Test
        run: aspect test --task:name=test -- //...

This skips everything else setup-aspect does: the token exchange, the generated ~/.aspect/bazelrc, the repository cache, and the Bazelisk install.

Install the Aspect CLI manually from GitHub

Visit the Aspect CLI Releases page on GitHub to download the appropriate binary for your platform, such as aspect-launcher-aarch64-apple-darwin for macOS arm64, or equivalents for other architectures and operating systems.

macOS example

Download the aspect-launcher-aarch64-apple-darwin binary from the Aspect CLI Releases page.

In your terminal, run these commands to clear the untrusted developer attribute, make the binary executable, and move it to your PATH:

xattr -c ~/Downloads/aspect-launcher-aarch64-apple-darwin
chmod u+x ~/Downloads/aspect-launcher-aarch64-apple-darwin
sudo mv ~/Downloads/aspect-launcher-aarch64-apple-darwin /usr/local/bin/aspect

Keep your team typing `bazel` with the `tools/bazel` wrapper

A tools/bazel wrapper in your workspace routes each bazel invocation to the right tool (aspect for the verbs it wraps, vanilla bazel for everything else) and aspect setup tools-bazel-wrapper installs it.

Usage telemetry

The launcher and CLI send usage telemetry. Set DO_NOT_TRACK to any value to turn it off:

export DO_NOT_TRACK=1

Community

Join the Aspect Community Slack, Aspect’s free community support. Ask in #help for general support. Join the discussion and see what others are building with the Aspect CLI and Aspect Extension Language (AXL) in the #cli and #axl channels. For Bazel and the Bazel rulesets, Bazel Slack is the best place for support and discussion. Ask about Aspect’s rules_js in #javascript and rules_py in #python.

​Install with curl

​Updating with curl

​Install with Homebrew (macOS)

​Updating with Homebrew (macOS)

​Install the Aspect CLI with direnv and multitool

​Install with GitHub Actions

​Without setup-aspect

​Install the Aspect CLI manually from GitHub

​macOS example

​Keep your team typing bazel with the tools/bazel wrapper

​Usage telemetry

​Community

Install with curl

Updating with curl

Install with Homebrew (macOS)

Updating with Homebrew (macOS)

Install the Aspect CLI with `direnv` and `multitool`

Install with GitHub Actions

Without `setup-aspect`

Install the Aspect CLI manually from GitHub

macOS example

Keep your team typing `bazel` with the `tools/bazel` wrapper

Usage telemetry

Community