aspect setup tools-bazel-wrapper

Put a tools/bazel shell wrapper in your workspace and Bazelisk runs it on every bazel invocation. The wrapper sends each command to the right tool: aspect for the verbs aspect wraps (build, test, lint, format, gazelle, buildifier, delivery, any custom .axl task), and vanilla bazel for everything else (query, info, clean, …). Your arguments are forwarded verbatim. The wrapper never inspects or rewrites a flag; it only picks which binary to run. aspect then forwards each flag it doesn’t define to Bazel in the slot you typed it in: after the verb as a command option, before it as a startup option. A flag the task defines itself stays with the task. See flag passthrough.

You type	What runs
`bazel build //... --keep_going`	`aspect build //... --keep_going`
`bazel test //... --test_output errors`	`aspect test //... --test_output errors`
`bazel --output_base /tmp/o build //...`	`aspect --output_base /tmp/o build //...`
`bazel lint --config=ci //src/...`	`aspect lint --config=ci //src/...`
`bazel query 'deps(//foo)'`	vanilla `bazel`, unchanged
`bazel my-custom-task //...`	`aspect my-custom-task //...`

Requires Bazelisk. The tools/bazel hook is a Bazelisk feature; the real bazel binary doesn’t look for it. It works when the bazel on your team’s PATH is Bazelisk.

bazel run stays on vanilla bazel by default: aspect run exists, but its semantics don’t match bazel run closely enough to replace it transparently yet. Reach for aspect run directly when you want it, or add run to the verb list below once you’ve validated it for your workflows. The Aspect CLI can drop the wrapper in for you. From anywhere in your workspace:

aspect setup tools-bazel-wrapper

This downloads the wrapper and its reference doc from the latest release tag (never main), writes tools/bazel (executable) and tools/bazel.md, and prints optional snippets for your shell’s rc file that toggle the escape hatches below. Re-running is idempotent: an up-to-date copy is left alone, and a newer release is offered as an upgrade.

Flag	Default	What it does
`--version <ref>`	`latest`	The aspect-cli release tag or commit SHA to take the wrapper from. `latest` resolves the newest release tag
`--check`	off	Exit non-zero when `tools/bazel` is missing or differs from `--version`, writing nothing. Use it as a CI gate
`--dry-run`	off	Print what would change without writing or deleting anything
`--uninstall`	off	Remove `tools/bazel` and `tools/bazel.md`. Refuses a `tools/bazel` that isn’t the Aspect wrapper. Can’t be combined with `--check`
`--yes`	off	Skip the confirmation prompt when upgrading or uninstalling, and replace a `tools/bazel` that isn’t the Aspect wrapper
`--all-shells`	off	Print the rc snippets for bash, zsh and fish instead of only the shell in `$SHELL`

Requires Aspect CLI v2026.39.10 or newer. On an older release, install the wrapper by hand instead, as shown next.

Or drop it in by hand:

mkdir -p tools
base=https://raw.githubusercontent.com/aspect-build/aspect-cli/v2026.39.10/tools
curl -fsSL "$base/bazel" -o tools/bazel
curl -fsSL "$base/bazel.md" -o tools/bazel.md
chmod +x tools/bazel
git add tools/bazel tools/bazel.md

Developers who prefer raw bazel for a shell session can set ASPECT_WRAPPER_SKIP=1 to bypass routing entirely.

Customize the verb routing

Two lists at the top of tools/bazel drive every routing decision. Edit them in your repo’s copy:

ASPECT_VERBS=(build buildifier delivery format gazelle lint test)

ASPECT_VERBS: the verbs routed to aspect. A verb in neither list is treated as a custom .axl task and also routes to aspect, so what listing one really buys is the fallback to vanilla bazel when aspect isn’t installed. That only makes sense for verbs Bazel also has.
BAZEL_VERBS: the closed set of Bazel commands. A verb here that is not in ASPECT_VERBS goes to vanilla bazel untouched (query, info, clean, mod, coverage, …). Update it only when Bazel adds a command.

Two common edits:

Send build / test to vanilla bazel instead. Remove them from ASPECT_VERBS and they fall through to the real bazel untouched. Keep the aspect-only verbs (lint, format, delivery, gazelle) listed so bazel lint and friends still reach aspect.
Add run, or your own aspect commands. Once aspect run suits your workflows, add run to ASPECT_VERBS so bazel run routes through it.

# Example: route bazel build/test to vanilla bazel, and wrap a custom "release" task
ASPECT_VERBS=(buildifier delivery format gazelle lint release)

The full reference (routing rules, every escape hatch, the trace output, and how the wrapper avoids recursing back into aspect) lives next to the script: tools/bazel.md.

​Customize the verb routing

Customize the verb routing