aspect-build / aspect-cli

correct, fast, usable: choose three

title	sidebar_label
Aspect CLI	Overview

The aspect CLI is a drop-in replacement for the bazel CLI that comes with Bazel.

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 product webpage: https://aspect.build/cli

Installation

Homebrew (MacOS)

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.

Manual (MacOS / Linux)

On any platform, you can download the 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.

Ensuring everyone on the team uses aspect

In an already-existing Bazel workspace, you can have bazelisk install the Aspect CLI just like it can install the standard Bazel CLI.

Note

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

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

Note that in all cases, the .bazelversion file continues to indicate which version of the Bazel tool is fetched and run beneath the wrapper.

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-dev channel.

For Enterprise

Aspect CLI is built by Aspect.

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

aspect-cli's Issues

release doesn't properly inline the runfiles tree

we publish the bare Go binary, but then at runtime

alexeagle@13-aspect-mbp ~ % aspect help tags
Unable to locate docs/help/topics/target-syntax.md in runfiles: could not locate runfiles directory
Failed to read : open : no such file or directory
Unable to locate docs/help/topics/info-keys.md in runfiles: could not locate runfiles directory
Failed to read : open : no such file or directory
Unable to locate docs/help/topics/tags.md in runfiles: could not locate runfiles directory
Failed to read : open : no such file or directory
Conventions for tags which are special

Warn user if Bazel version is floating

(no bazelisk, or using latest in .bazelversion, or no .bazelversion)

prettier formatting for markdown hurts source readability

# Tags

The `tags` attribute can appear on any rule, and can have arbitrary values. Some
tags have a special meaning to Bazel, and are listed below.

Tags on test and test_suite rules are useful for categorizing the tests. Tags on
non-test targets are used to control sandboxed execution of genrules and
Starlark actions, and for parsing by humans and/or external tools.

## Tags on test targets:

exclusive run no other test at the same time

is not as readable in a terminal as

Tags
====

The `tags` attribute can appear on any rule, and can have arbitrary values. Some
tags have a special meaning to Bazel, and are listed below.

Tags on test and test_suite rules are useful for categorizing the tests. Tags on
non-test targets are used to control sandboxed execution of genrules and
Starlark actions, and for parsing by humans and/or external tools.

Tags on test targets:
---------------------

exclusive run no other test at the same time

prettier/prettier#6013

maybe we should just fix it in prettier

Forward internal BES events to user specified BES server

At the moment we specify our own BES server and push events to it. Should the user pass in a BES server endpoint we should forward our events to the specified server instead of creating our own

Allow canned queries to live in the checked-in rc file

Currently canned queries live within the query code itself. This might do for built in canned queries, but users need to be able to define their own canned queries.

If a built in canned query and a user-defined canned query have the same name, the user defined version should be used

Readable output timing

Bazel prints
(19:29:48) INFO: Elapsed time: 4117.783s, Critical Path: 768.50s

What would be better:

• format the time better, print minutes or hours
• is this fast or slow compared with expected
• why did I spend so much more wall time than the critical path needed? basically tell me that the build spent a long time waiting for local resources due to --jobs flag or other controls

Allow plugins to be called when using the test verb

The plugin system is currently setup for the build verb and needs to be wired up for the test verb

Augment error message content

Users should be able to add a mapping in their checked-in aspect config file, from something to match in the bazel stdout (maybe a regex) to an additional error message to print.

This allows use cases like

• "anytime there's an error about protoc failing to compile, show a go/ link to my internal company knowledge base"
• "remind users to run the //:update_build_files target in my repo"

Note that we may have to distinguish both a user-preferences file and a config file checked into the project and shared with other engineers.

Plugin to upload telemetry

Allow devx team at a company to monitor the perf/usability of aspect across developer machines, uploading data so that the monitoring system can answer

• is it getting slower?
• do users get way more errors?
• which commands are commonly run?

https://opentelemetry.io/ would be a good example for a reference implementation.

rc file says where the data is uploaded

Make our vanity aspect.build go imports work with tooling

We should follow https://sagikazarmark.hu/blog/vanity-import-paths-in-go/
so that our savvy go imports for users actually work when they add a dependency on us and run go mod tidy

Figure out plugin protocol versioning evolution

Right now, we don't test or support older protocol versions. We need to come up with a better story for this. Perhaps the SDK could do some work when a plugin is too old and doesn't support a specific method? This task is broad and the outcome should be a small design doc with some POC.

Make aspect sync better than bazel sync

Users need a way to "fix" buggy external repositories.

Note: maybe the sync command should recommend you do something else

MacOS requires the application be signed by a developer

Otherwise you get the security error from the OS and have to go to the System Preferences -> Security tab to manually allow it.

Query: Validate incoming labels before passing them to query

After prompting the user for a label, we should do some validation on it. If they typed it wrong (typo, colon in the wrong place, etc) we could help them out by suggesting a label with a minimal edit distance from what they typed.

✔ why: Determine why targetA depends on targetB
Value for 'targetA': 
Value for 'targetB': 
ERROR: Error while parsing 'somepath(, )': syntax error at ', )'

It is not super helpful to give the error from query evaluation when we already knew something was wrong.

Custom command "outputs"

We've been deploying a tools/bazel wrapper with a custom verb, but it relies on https://docs.bazel.build/versions/4.2.2/command-line-reference.html#flag--incompatible_proto_output_v2 which is a no-op in Bazel 5.0

      "outputs")
          if [ -x ${TARGETS+x} ]; then
              echo -e "${RED}ERROR${CL} Requested an empty set of targets\nUsage: 'bazel outputs <targets>'"
              exit 1
          fi

          echo -e "Querying for outputs for ${TARGETS[*]}\n"

          for T in "${TARGETS[@]}"; do
              OUTS=$(${BAZEL_REAL} aquery "${T}" --include_commandline=false --output jsonproto 2> /dev/null |\
                  jq --raw-output '((.actions[]?.outputIds)[] as $ids | (.artifacts[] | select(.id | IN( $ids )))) as $art | $art.execPath')

              echo "${BOLD}${T}${CL}:"
              if [ -x ${OUTS+x} ]; then
                  echo -e "\t${YELLOW}No outputs${CL}"
              else
                  printf "\t${GREEN}%s${CL}\n" "${OUTS[@]}"
              fi
          done
      ;;

We should move this functionality into Go code so we don't rely on a jq query.

Log file to include when asking "why bazel slow"

One client has the problem that a linter lazily runs a bazel fetch in the background, and users can't tell what bazel was doing or why it was slow.

Write log file(s) to disk

• one big log that rolls?
• one log per invocation .<invocation_id>.bazel.log or sth

Include the command_log into this file
If you ran with --profile then we want that data
Include some 'doctor' info about your machine

• find things about my bazel setup or about my machine that might be causing problems
• produce output suitable to include when escalating for support

Need to take care not to include secrets like your auth tokens

Remembers what was run last. You can ask for "print the failing log" and it finds the one from last execution of aspect test. Keeps historical execution logs around to help debug past builds.

bazel query interactive GUI

Nx has something like this.

They use https://cytoscape.org/
with https://github.com/cytoscape/cytoscape.js-popper for augmenting with tooltips and
https://github.com/cytoscape/cytoscape.js-dagre since we are showing DAGs

Add a showGraph option to query that will open a query graph in a browser

POC was already completed and removed in: 6593d4f

From the PR #57

feature: plugin system using hashicorp/go-plugin

Initially, this should support the current fix-visibility plugin.

logging to disk

• show these logs via the tool (aspect replay)
• user can upload logs when asking for help
• log rotation, exec log included
• demux into more than one log (maybe)

Do something with bazel-testlogs/*/some/test.cache_status

This file is binary proto but probably contains data the user cares about

Allow plugin custom commands to be disabled from the plugin config

We want to be able to enable / disable certain custom commands from the plugin config. A case where this might be useful...
PluginA implements custom commands:
Foo
Bar

PluginB implements custom commands:
Foo
Baz

These 2 plugins would conflict with each other unless I was able to disable Foo on PluginB for example

Missing user level config file results in confusing error message

When running aspect clean for the first time the user is asked if they want to make their choice the default for aspect clean. If you choose yes and have not yet created a config file, it will throw the following style of error:

Error: failed to update config file: Config File ".aspect" Not Found in "[/Users/jesse]"

This is problematic in that it claims to be looking for a file named .aspect when in reality it looks for a file named .aspect.yaml. At first glance I created the file: /Users/jesse/.aspect and only when it failed for a second time I had to look into the source code to determine I actually needed /Users/jesse/.aspect.yaml.

This does not make for a good user experience and we should likely either just create the file (with permission of the user?) or supplement the error message in some way. I say "supplement" instead of "fix" because the given section of the error message appears to be thrown from the viper library

Support json output for query

Currently bazel only supports XML output, but it does have proto too.. Either way, allow outputting JSON and take a jq filter to further filter down the output needed.

Keep some bazel config in sync with sources

Examples:
.bazelignore should have all nested node_modules folders
--deleted_packages should have examples/*/BUILD locations

Canned queries should include the verb (query, cquery, aquery)

Currently canned queries will only run using standard query. We should extend this so that instead of assuming we used query, allow the query type to be specified (query, cquery, aquery) when the canned query is defined

Help me run bazel build/test inside a docker container

If I'm on Mac, or need a precise version of fonts installed to get a pixel-perfect screenshot test, then it's hard for me to rely on my host machine to run bazel, due to non-hermeticities or platform dependencies.

I'd like some new verb like bazel docker-build that just does the build in a container.

https://github.com/aspect-build/bazel/releases/tag/4.0.0 shows one recipe I used to build bazel itself.

Another example:

$ cat tools/bazel 
#!/usr/bin/env bash

set -o pipefail -o errexit -o nounset

ARGS=( "$@" )

function bazel_in_docker {

    mkdir -p /tmp/build_output/

    echo >&2 "Running bazel under docker, output root in /tmp/build_output"

    docker_args=(
        -v "$PWD":/workspace
        -v /tmp/build_output:/tmp/build_output
        -v /var/run/docker.sock:/var/run/docker.sock
        -v "$HOME/.npm:/home/.npm"
        -w /workspace
        -e USER="$(id -u)"
        -u="$(id -u)"
        -e HOME=/home
        -p 3000:3000
    )

    set -x
    docker run \
        "${docker_args[@]}" \
        l.gcr.io/google/bazel:$(head -1 .bazelversion) \
        --output_user_root=/tmp/build_output \
        ${ARGS[@]}
    set +x
}

case "${ARGS[0]}" in
    "dbuild")
        ARGS[0]="build"
        bazel_in_docker
    ;;
    "drun")
        ARGS[0]="run"
        bazel_in_docker
    ;;
    *)
        # replace the current process with bazel
        # so that `pstree` and other tools don't see our wrapper
        # as bazel's parent process
        exec -a bazel "${BAZEL_REAL}" "$@"
esac

feature request: attribute suggestions

For example, when bazel gives an error like "no such attribute 'contents' in 'write_file' rule" we should use the heuristics other tools use and output "did you intent to write 'content'?"

aspect help tags

show all the common tags and what they mean
from https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes

help manage my disk space

Bazel workspaces can occupy a lot of space. bazel clean will fix that, but first you have to know that Bazel is the reason you're low on disk, and how big each Bazel workspace is.

Support "watch mode"

We should add a plugin that does the same thing as bazel-watcher.

Give the user commands like

• aspect run //one:target where that target is tagged with ibazel_notify_changes -> like ibazel run //one:target
• aspect test //one:target -> like ibazel test //one:target (??)
• aspect watch //one:target -> like ibazel run //one:target
• aspect watch //target/pattern/... -> like bazel build //target/pattern/...

/cc @achew22

User settings distinct from project settings

Viper allows us to make a second instance.

Users need their personal preferences and also check in workspace preferences.

In the MVP, let's try to make these two files totally distinct so that a given setting can only exist in one or the other.
But at some point this will probably break down and there will have to be inheritance like bazelrc

feature: add --shell flag

In pants, the --shell flag can be used to drop the user into the exec root (perhaps after a failed build?). This can be handy for the user to dig around the sandbox where the previous command ran and do any debugging.

This flag would likely imply:

• --sandbox_debug
• --verbose_failures
• --subcommands

Prompt user to find out if they would like to use cquery instead of standard query by default

On the first run of query (like clean) we should ask the user "Would you rather use cquery from now on".

canned queries

in interactive mode, prompt for each placeholder values

releases don't appear as "clean"

install latest GH release, then

% aspect version
Aspect version: v0.0.6 (with local changes)

I fought with this for a couple hours but didn't figure it out. Something about the GH actions environment.

do something useful for `aspect build` or `aspect test`

Bazel's behavior is pretty dumb

alexeagle@system76-pc:~/Projects/aspect-cli$ bazel build
WARNING: Usage: bazel build <options> <targets>.
Invoke `bazel help build` for full description of usage and options.
Your request is correct, but requested an empty set of targets. Nothing will be built.
INFO: Analyzed 0 targets (0 packages loaded, 0 targets configured).
INFO: Found 0 targets...
INFO: Elapsed time: 0.079s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action
alexeagle@system76-pc:~/Projects/aspect-cli$ bazel test
INFO: Build option --test_env has changed, discarding analysis cache.
INFO: Analyzed 0 targets (0 packages loaded, 0 targets configured).
INFO: Found 0 test targets...
INFO: Elapsed time: 0.124s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action
INFO: Build completed successfully, 1 total action

Proposal

When interactive:
bazel build prompts

what would you like to build?
all targets in current folder /path/to (this is the workspace-relative path you're in)
all targets beneath current folder
specific target patterns

if you choose target patterns, we help you select them

and then prompts

remember this for next time?

configure my IDE

for whatever targets I'm working on, I want those to appear in my IDE without red squiggles.

figure out what buck project does and mimic:
https://buck.build/command/project.html

Probably support VScode and jetbrains

Allow plugins to mutate the Build Events

Plugins should be able to omit/append/modify to the build events
Other plugins running later on the stack should see the edits.
BuildBuddy or other remote UI should see the edits.

Passing --config flag does not override config load location

Current Behaviour: When I call aspect --config ./foo.yaml someVerb config is loaded from the default location

Expected Behaviour: When I call aspect --config ./foo.yaml someVerb config is ONLY loaded from the specified config file

Logic can be found in https://github.com/aspect-build/aspect-cli/blob/main/cmd/aspect/root/root.go
We attempt to set the cfgFile variable from the command line arguments but it appears that this never gets set.

Current execution environment: M1 Macbook Air, zsh shell

prompt to run 'bazel run' suggestions in test failures

When a test says "bazel run //blah:update" to accept new output

we should offer to do that for you. Like our pattern for checked-in build outputs (docs/ folders in rulesets for example)

Extend plugin protocol to support custom command

I can't currently write a plugin that adds a command like aspect rebase for example.

Save bazel commands that will be run to a log file

• Everytime the aspect-cli runs a bazel command we should save it to a log file (useful for debugging, learning, etc)
• Everytime the aspect-cli run we should inform the user where they can find the log of bazel commands (should add a config option to disable this as well in case the user does not want this to happen)

Consider replacing the C++ client

In the future, we might totally replace the bazel C++ client, and this tool
would be a gRPC client of the bazel server.

It means we have to parse the bazel server's startup options, and also have to manage the JVM process that hosts the server.

feature: auto fix visibility based off the error

Based off the visibility errors generated by bazel, eg:

ERROR: /blah/BUILD.bazel:0:00: in py_library rule //foo/bar
 target '//baz:baz' is not visible from target '//foo/bar'. Check the visibility declaration of the former target if you think the dependency is legitimate

Suggest auto fixes to the user if they accept that the dependencies are infact, legitimate.

Add an "x-trace" mode

We want an x-trace mode of some sort (to be named) that will echo the bazel commands it is about to run to the command line before it runs them (similar to bazel's -s).

Support common flags

Currently this is an error:

$ aspect build --nobuild
Error: unknown flag: --nobuild

We have the code to parse bazel help flags-as-proto already, so we know all the flags that exist on the bazel build command and others.

We could just programatically add all the flags to all the commands in cobra. However then we're as bad as bazel, try running bazel help build and then scroll up forever.

Instead we probably want to:

• expose super-obvious flags in the CLI for all users
• permit "undocumented" flags to be passed through to Bazel
• [opt] user/repo settings file allows for more flags to appear.

Idea: maybe if you use a flag the first time, we add it to "your personal flags". But OTOH once you've used a flag, it's probably not important to you for it to appear in the help.

Add aspect run

Clearly commonly used Bazel command.

Think a bit about whether run already does the right thing. Like the working directory is hard to reason about right now.

Should we help the user discover --run_under use cases?
We could help you with the -- in the wrong place.

multi-run is also a thing! Check what atlassian did.

Add `aspect reset` command

• Add a way to reset saved preferences
• Either via interactive command or options

Go into setup mode if running outside a Bazel workspace

note for later (maybe a TODO?) we should offer to help if the user actually meant the cwd to be a workspace - go interactive and into a setup mode

Originally posted by @alexeagle in #83 (comment)