title	sidebar_label
Aspect CLI	Overview

Aspect CLI (aspect) is a drop-in replacement for the CLI that comes with Bazel that adds additional features and extensibility to the popular polyglot build system from Google.

Why Aspect CLI?

Every organization has a different engineering culture and developer stack. Bazel was designed for Google's workflows, not yours. Many companies have found they have to write a wrapper around Bazel. This starts out as a small need to shim something in the developer workflow, and is often an untested Bash script living in /tools/bazel which Bazelisk understands as a wrapper script.

Over time, the wrapper accumulates more code, and is a constant source of developer distress.

See more on our docsite: https://docs.aspect.build/cli/

Licenses

Aspect CLI OSS

Aspect CLI OSS, the open-source, open-core portion of the Aspect CLI, is found in this repository and is Apache 2 licensed.

Aspect CLI

The standard Aspect CLI is built on top of the open-source, open-core portion found is this repository and is licensed under the Aspect Community License. The parts of the Aspect CLI that are not found in this repository are closed source.

We intend for Aspect CLI to remain free for individuals (only for personal use), Small Business (fewer than 50 employees), and non-profit or academic institutions. Please contact Aspect at https://aspect.build if you would like to use the Aspect CLI and fall outside of free use.

Installation

Aspect CLI OSS

Bazelisk (MacOS / Linux)

Aspect CLI OSS can be installed in an existing Bazel workspace using bazelisk.

Note

This approach doesn't provide the aspect init command, which has to run outside a Bazel workspace.

From the OSS releases page, copy the .bazeliskrc snippet into your .bazeliskrc file to install Aspect for all developers in the target repository.

The underlying version of Bazel can be configured in your .bazelversion file or the BAZEL_VERSION environment variable.

Manual (MacOS / Linux)

On any platform, you can download the Aspect CLI OSS aspect binary for your platform on our Releases page and add it to your PATH manually.

Note, if you manually install for MacOS, you can bypass the "Unknown Developer" dialog by running xattr -c $(which aspect) before launching aspect.

Aspect CLI (standard)

Homebrew (MacOS)

To install the Aspect CLI on MacOS, you can run

% brew install aspect-build/aspect/aspect

This installs the aspect command and also links it to bazel, just like the bazelisk installer does.

Bazelisk (MacOS / Linux)

Aspect CLI can be installed in an existing Bazel workspace using bazelisk.

Note

This approach doesn't provide the aspect init command, which has to run outside a Bazel workspace.

Configure bazelisk to use the Aspect CLI for all developers in a repository by adding the following to `.bazeliskrc` in the repository root:

BAZELISK_BASE_URL=https://static.aspect.build/aspect
USE_BAZEL_VERSION=aspect/xxxx.x.x

Check the Aspect CLI Homebrew formula for latest version of Aspect CLI.

Note

An Aspect CLI releases page with release notes and past releases is coming soon.

The underlying version of Bazel can be configured in your .bazelversion file or the BAZEL_VERSION environment variable.

Windows

Windows releases are no longer published as of v5.5.0. This is due to a new dependency on go-tree-sitter which has a CGO dependency that makes cross compiling to Windows difficult.

To produce Windows releases will require some engineering work to resolve the CGO cross compilation issues. Please let us know if you require a Windows Aspect CLI binary. In the meantime, we recommend using WSL2 on Windows.

Usage

Just run aspect help to see the available commands. Some are the standard ones you know from Bazel, and others are new, such as print and docs.

Write a plugin

Aspect's plugin system allows you to fit Bazel into your team's development process, with custom commands, behaviors, and integrations.

A plugin is any program (written in any language) that serves our gRPC protocol. The easiest way to get started is to clone our starter template repo.

See the Plugin Documentation for more information on how to write a plugin.

Need help or having issues?

If you think you've hit a bug please file a Bug Report.

You can also find us on Bazel Slack on the #aspect-build channel.

For Enterprise

Aspect CLI is built by Aspect.

See our website at http://aspect.build to learn more about our product offerings.