Pin the Aspect CLI version

The aspect binary you install is a thin launcher: it provisions and execs the real aspect-cli for your project. The launcher decides which CLI version to run by reading a single file in your repository:

<repo-root>/.aspect/version.axl

Pinning a version here means every developer and every CI runner in the project executes the same aspect-cli, regardless of how recently they installed the launcher.

Because AXL-powered tasks (aspect build, aspect test, aspect lint, aspect delivery) ship with the CLI, bumping the version in .aspect/version.axl pulls in newer task behavior independent of any Aspect Workflows CI runner upgrade.

Pin a version

Create .aspect/version.axl at your repository root, alongside MODULE.bazel (or MODULE.aspect):

version("2026.41.50")

These docs assume Aspect CLI 2026.41.50 or later. The launcher downloads v2026.41.50 directly from the Aspect CLI GitHub Releases the first time it’s needed and caches the binary locally. A pinned version never falls back to a different release.

How the launcher finds the pin

The launcher walks up from the working directory to find the project root:

The nearest directory containing MODULE.aspect or .aspect/version.axl, not counting your home directory.
Otherwise, the nearest directory containing a Bazel boundary file such as MODULE.bazel or REPO.bazel.
Otherwise, the working directory.

It then reads the version from the first of these that exists:

.aspect/version.axl in the project root.
User-level pin: ~/.aspect/version.axl, same syntax. It sets a default CLI version for any project root without its own pin, including a Bazel workspace that has no .aspect/version.axl.
Floating mode: the launcher queries the GitHub releases API for the latest release and downloads that. The resolved tag is cached for 24 hours.

A project-level .aspect/version.axl always wins over ~/.aspect/version.axl.

Floating mode is convenient for one-off use, but every contributor and CI runner can end up on a different aspect-cli version. Pin a version (per project, or per user via ~/.aspect/version.axl) for any project where reproducibility matters.

Custom sources

The optional sources list overrides where the launcher looks for the CLI binary. Sources are tried in order; the first one that succeeds wins.

version(
    "2026.41.50",
    sources = [
        local("bazel-bin/cli/aspect"),
        github(
            org = "aspect-build",
            repo = "aspect-cli",
        ),
    ],
)

When sources is omitted, the launcher tries the GitHub release first, then Aspect’s CDN mirror of the same assets.

`local(path)`

Use a binary at a path relative to the repository root. Useful when developing the CLI locally:

local("bazel-bin/cli/aspect")

The file is copied into the launcher cache on each invocation so that build-system clean operations don’t break a running CLI.

`github(org, repo, tag?, artifact?)`

Download from a GitHub release:

github(
    org = "aspect-build",
    repo = "aspect-cli",
)

When tag and artifact are omitted the launcher derives defaults:

tag defaults to v{version} (e.g. v2026.41.50)
artifact defaults to {repo}-{target} (e.g. aspect-cli-aarch64-apple-darwin)

Override either with explicit strings if you publish releases under a different convention:

github(
    org = "my-org",
    repo = "aspect-cli-fork",
    tag = "release-{version}",
    artifact = "aspect-cli-{os}-{arch}",
)

`http(url)`

Download from an arbitrary URL, for example an internal mirror:

http(
    url = "https://cdn.example.com/aspect-cli/v{version}/{artifact}",
)

http() doesn’t support custom request headers.

Template variables

tag, artifact, and url strings support these placeholders, replaced at runtime:

Variable	Example	Description
`{version}`	`2026.41.50`	The version from the `version()` call
`{os}`	`darwin`, `linux`	Operating-system kernel name
`{arch}`	`aarch64`, `x86_64`	CPU architecture (Bazel naming)
`{target}`	`aarch64-apple-darwin`, `x86_64-unknown-linux-musl`	LLVM target triple
`{artifact}`	`aspect-cli-aarch64-apple-darwin`	`http` `url` only: the default release asset name, including the `-debug-` infix when the debug build is requested. Use it for a mirror of the GitHub release assets.

These are the only supported placeholders. version.axl is parsed as Starlark syntax but not evaluated: only string literals and function-call structure are extracted, so expressions, variables, and conditionals aren’t available.

Caching

Downloaded binaries are cached under the system cache directory:

macOS: ~/Library/Caches/aspect/launcher/downloader/
Linux: ~/.cache/aspect/launcher/downloader/

The cache path is derived from a SHA-256 hash of the tool name and source URL, so different versions coexist without conflict. To move the cache, set ASPECT_LAUNCHER_CACHE to a root directory; binaries go under <root>/downloader/. Set ASPECT_DEBUG=1 to log the launcher’s download and cache resolution.

Debug build of the CLI

Releases can also publish a debug build of the CLI: unstripped and built with debug assertions, so a crash report resolves to function and line. It’s larger and slower. Request it with debug = True:

version("2026.41.50", debug = True)

or for one invocation, with the ASPECT_DEBUG_CLI environment variable set to any non-empty value. When a release has no debug asset, the launcher falls back to the primary binary. A source with an explicit artifact always gets that artifact.

CI considerations

CI runners share the same launcher behavior as developer machines, so a committed .aspect/version.axl pins the CLI version everywhere at once.

Aspect Workflows CI runners ship with the launcher pre-installed.
GitHub Actions / other CI: see Install the Aspect CLI for installing the launcher in your CI image. Once installed, the launcher reads the same .aspect/version.axl from the checkout.

​Pin a version

​How the launcher finds the pin

​Custom sources

​local(path)

​github(org, repo, tag?, artifact?)

​http(url)

​Template variables

​Caching

​Debug build of the CLI

​CI considerations

Pin a version

How the launcher finds the pin

Custom sources

`local(path)`

`github(org, repo, tag?, artifact?)`

`http(url)`

Template variables

Caching

Debug build of the CLI

CI considerations