> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Overview of built-in Aspect CLI AXL tasks including aspect build, test, format, lint, delivery, gazelle, and buildifier on any Bazel CI system.

Aspect CLI ships built-in tasks — `aspect init`, `aspect build`, `aspect test`, `aspect run`, `aspect format`, `aspect lint`, `aspect delivery`, `aspect gazelle`, plus `aspect buildifier` as a one-liner you opt into — that run on **any CI system**. Built-in tasks work out of the box; customize their behavior in `.aspect/config.axl`. Extend the CLI with your own tasks by dropping `.axl` files into `.aspect/` — they're auto-discovered. Invoke any task with `aspect <task>` in your CI YAML and it works the same whether the pipeline runs on GitHub Actions, Buildkite, GitLab, CircleCI, a self-hosted runner, or your local machine.

On [Aspect Workflows](/docs/aspect-workflows/overview) self-hosted runners, tasks automatically detect the environment and configure remote caching, remote build execution, and pre-warmed NVMe output bases — no extra setup required.

<Tip>
  Run `aspect help` from inside your repo to list every task available (built-ins plus any custom ones). For per-task help, `aspect <task> --help` shows all flags with their defaults.
</Tip>

## Task reference

| CLI command         | What it does                                        | Guide                                             |
| ------------------- | --------------------------------------------------- | ------------------------------------------------- |
| `aspect init`       | Scaffold a new Bazel workspace from a preset        | [aspect init](/docs/cli/tasks/init)               |
| `aspect build`      | Build Bazel targets                                 | [aspect build & test](/docs/cli/tasks/build_test) |
| `aspect test`       | Run Bazel tests                                     | [aspect build & test](/docs/cli/tasks/build_test) |
| `aspect run`        | Build and run a binary target                       | [aspect run](/docs/cli/tasks/run)                 |
| `aspect format`     | Format source files                                 | [aspect format](/docs/cli/tasks/format)           |
| `aspect buildifier` | Format Starlark files (opt-in via `format.alias()`) | [aspect buildifier](/docs/cli/tasks/buildifier)   |
| `aspect lint`       | Run linters                                         | [aspect lint](/docs/cli/tasks/lint)               |
| `aspect gazelle`    | Generate and sync BUILD files                       | [aspect gazelle](/docs/cli/tasks/gazelle)         |
| `aspect delivery`   | Deliver build artifacts                             | [aspect delivery](/docs/cli/tasks/delivery)       |

## Configuration

`.aspect/config.axl` at the root of your repository is the central place to customize tasks and wire up task hooks. It is evaluated once per `aspect <task>` invocation; values can branch on environment variables, CLI flags, or any Starlark expression.

A minimal config enabling artifact uploads for CI:

```python title=".aspect/config.axl" theme={null}
load("@aspect//feature/artifacts.axl", "ArtifactUpload")
load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))

    if is_ci:
        ctx.traits[BazelTrait].extra_flags.extend([
            "--config=ci",
        ])

    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"
    ctx.features[ArtifactUpload].args.upload_profile = True
```

See [Running tasks in CI](/docs/cli/tasks-ci) for complete CI YAML for all four supported providers.

## Running tasks in CI

The same `aspect <task>` command runs identically in CI and on a developer machine — no wrapper scripts, no CI-specific flags. The CLI reads the `CI` environment variable to activate CI-specific behaviors (remote cache usage, artifact upload, status checks).

**Minimal CI example (GitHub Actions):**

```yaml theme={null}
- uses: actions/checkout@v6
- run: aspect build //...
- run: aspect test //...
```

Set `ASPECT_API_TOKEN` in the job environment to unlock GitHub Status Checks, Buildkite Annotations, and GitLab job annotations. Without it, tasks still build and test normally. See [Running tasks in CI](/docs/cli/tasks-ci) for platform-specific pipeline YAML.

## Version pinning

Pin the CLI version in `.aspect/version.axl` to ensure reproducible behavior:

```python theme={null}
version("2026.27.7") # minimum for all built-in tasks documented above
```

See [version pinning](/docs/cli/version-pinning) for the full set of source options.