Skip to main content
The Aspect CLI can be installed using several methods. All of them install the aspect-launcher, a small binary added to your PATH as aspect. This launcher downloads and runs the version of the Aspect CLI binary configured in your repository. It operates similarly to how bazelisk fetches the configured version of Bazel, or how nvm or n- manages Node.js versions. The latest releases can be found at https://github.com/aspect-build/aspect-cli/releases.
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
This installs the aspect-launcher binary as aspect on your PATH.

​
Updating with curl

To update the aspect-launcher with curl, re-run the installation script: 
curl -fsSL https://install.aspect.build | bash

​
Install with Homebrew (macOS)

To install via Homebrew, run the following command: 
brew install aspect-build/aspect/aspect
Alternatively, tap the repository first and then install: 
brew tap aspect-build/aspect
brew install aspect
This installs the aspect-launcher binary as aspect on your PATH.

​
Updating with Homebrew (macOS)

To update the aspect-launcher with Homebrew, run the following commands: 
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 Starter repositories at bazel-starters on GitHub.
  1. Add aspect to the multitool lockfile, as shown in this example.
  2. 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. It installs the launcher, installs Bazelisk (unless bazel is already on PATH), wires --disk_cache / --repository_cache to the GHA cache, and exchanges your ASPECT_API_TOKEN for a short-lived JWT — all in one step. The same one-liner works on provider-hosted runners (ubuntu-latest, macos-latest) and on Aspect Workflows CI runners. 
permissions:
  id-token: write    # required for Aspect CLI's ArtifactUpload feature

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 test --task-key=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

If for some reason you’d rather install the launcher inline (or you’re on a CI provider without an equivalent action — Buildkite, GitLab, CircleCI), the curl one-liner works: 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Aspect CLI
        run: curl -fsSL https://install.aspect.build | bash
      - name: Test
        run: aspect test --task-key=test -- //...
You give up GHA caching, the API-token-to-JWT exchange, and the Bazelisk install — all of which setup-aspect does for you.

​
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

  1. Download the aspect-launcher-aarch64-apple-darwin binary from the Aspect CLI Releases page.
  2. 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