Aspect CLI tasks - Aspect Build

A task is a named unit of work you run with aspect <task>: build and test, format, lint, generate BUILD files, deliver artifacts. Tasks that run Bazel add what CI needs on top of it: status checks, PR comments, artifact upload and retries on transient errors. Every task runs the same on your machine and on any CI system. The Aspect CLI ships with the built-in tasks listed below, and you customize them in .aspect/config.axl. You can also add your own: a custom task is an .axl file in .aspect/, discovered automatically and run the same way as a built-in one. Run and define tasks shows how to write one. On Aspect Workflows CI runners, tasks configure Bazel for the runner; see Aspect Workflows runners.

Run aspect help from inside your repo to list every task available, built-in and custom. aspect <task> —help shows a task’s flags with their defaults.

Built-in tasks

Build & test

Command	What it does
`aspect build`	Build Bazel targets
`aspect test`	Run Bazel tests
`aspect run`	Build and run a binary target

Formatting & linting

Command	What it does
`aspect format`	Format source files
`aspect buildifier`	Format Starlark files (opt-in via `format.alias()`)
`aspect lint`	Run linters

BUILD file generation

Command	What it does
`aspect gazelle`	Generate and sync BUILD files

Delivery

Command	What it does
`aspect delivery`	Deliver build artifacts

Affected targets

Command	What it does
`aspect cache diff`	List test targets affected by the current tree vs. the remote cache

Agents

Command	What it does
`aspect mcp`	Serve read-only build and test results to AI agents over MCP

CI runners

Command	What it does
`aspect ci warming`	Fill a runner’s Bazel caches and upload the warming archive
`aspect ci runner-health-check`	Run the Workflows runner health check
`aspect ci runner-metadata`	Print the Workflows runner metadata

Setup

Command	What it does
`aspect init`	Scaffold a new Bazel workspace from a preset
`aspect axl add`	Add an AXL module from a GitHub release to `MODULE.aspect`
`aspect setup bazelrc`	Write a Bazel rc so vanilla `bazel` calls reach your deployment. Also reachable as `aspect ci bazelrc`
`aspect setup tools-bazel-wrapper`	Install the `tools/bazel` wrapper that routes `bazel` through `aspect`
`aspect setup workspace-data`	Print build metadata as Bazel workspace status

Housekeeping

Command	What it does
`aspect gc`	Reclaim Bazel output bases and download-cache entries nothing is using
`aspect output-bases`	List this machine’s output bases: state, server memory, branch, workspace and size

Worktrees

A pool of reusable worktree slots that keep their Bazel output base — and its server — across branches. See the worktrees guide.

Command	What it does
`aspect worktree add`	Check a branch out into the warmest free slot
`aspect worktree release`	Give a slot back, keeping its output base for the next branch
`aspect worktree list`	Report every slot in the pool and what it has kept
`aspect worktree path`	Print one slot’s path — the call agents make
`aspect worktree inspect`	Report one slot in detail
`aspect worktree prune`	Release slots nothing is using any more

Authentication

Command	What it does
`aspect auth`	Log in, and configure and switch deployments (`login`, `logout`, `status`, `configure`, `use`, `remove`)

GitHub App

Command	What it does
`aspect github token`	Mint a short-lived GitHub App token for a repository

Discovery commands

These aren’t tasks. aspect help lists them under Commands.

Command	What it does
`aspect describe`	Print the command index and feature names as JSON; `aspect describe '<task>'` prints one task’s flags with their effective defaults
`aspect feature`	List the built-in features; `aspect feature <name>` shows a feature’s flags
`aspect version`	Print the CLI version this repository resolves to

Flags every task accepts

Flag	What it does
`--task:name=<name>`	Short name identifying this invocation (`A-Za-z0-9`, `_`, `-`). Set it on every CI invocation: status checks, artifacts and delivery state are keyed on it. Defaults to a name derived from the CI job on CI, and `<kind>-<random suffix>` off CI. See Task name.
`--task:friendly-name=<label>`	Human-readable label shown on status surfaces. Defaults to `--task:name`.
`--task:id=<uuid>`	UUID identifying this invocation. Generated when unset.
`--task:timing-summary=<level>`	Phase-timing breakdown after the completion line: `none`, `total`, `short`, or `detailed` (default).

Configure tasks in .aspect/config.axl (AXL), pin the CLI version in .aspect/version.axl (version pinning), and see Running tasks in CI for pipeline YAML for each CI provider.

​Built-in tasks

​Build & test

​Formatting & linting

​BUILD file generation

​Delivery

​Affected targets

​Agents

​CI runners

​Setup

​Housekeeping

​Worktrees

​Authentication

​GitHub App

​Discovery commands

​Flags every task accepts

Built-in tasks

Build & test

Formatting & linting

BUILD file generation

Delivery

Affected targets

Agents

CI runners

Setup

Housekeeping

Worktrees

Authentication

GitHub App

Discovery commands

Flags every task accepts