> ## 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.

# Introduction

> Hands-on course for extending Bazel with AXL: custom aspect subcommands, BUILD file generators in Starlark, and CI reporting you write yourself.

{!user.loggedIn ? (
<Tip>
<a href="https://auth.aspect.build/oauth/account/sign-up">Sign up</a> for a free Aspect account to access the full training course. Already have one? <a href="/login?redirect=%2Flearning%2Faspect-160">Log in</a>.
</Tip>
) : null}

Bazel is famously extensible, and almost all of that extensibility points inward, at defining new rules. The part of your build that engineers actually touch every day sits outside Bazel: the CLI they type, the scripts that wrap it, the BUILD files somebody has to write, and the CI plumbing that decides what they see when it breaks. That layer is usually Bash, Make, and YAML, and every monorepo grows its own.

AXL, the Aspect Extension Language, is a Starlark dialect built into the open-source [Aspect CLI](/docs/cli/overview). It's how you program that outside layer: custom subcommands, BUILD generators, and the reporting that comes back from CI. Same language as your `.bzl` files. No Go plugin to compile, no new YAML schema to learn.

## What you'll build

By the end of this course you'll have written, and run, all of the following against a real Bazel repository:

* A custom `aspect` subcommand with typed arguments, phases, and a proper exit code.
* A task that drives Bazel and reads its Build Event Stream live, target by target.
* Repository-wide policy in `.aspect/config.axl`: flags, task defaults, pre- and post-task hooks, and rewritten repro commands.
* A BUILD file generator in Starlark that encodes your repo's conventions, including cross-package dependency resolution.
* A CI integration that posts lint findings as inline comments on a pull request, plus a status surface of your own, written in about twenty lines.

## Who it's for

Bazel users of all experience levels. Newcomers curious about Starlark will be fine; platform and developer-experience teams looking to standardize how their engineers interact with Bazel are the people this was written for.

Comfort with BUILD files and labels helps. Prior Starlark experience is not required, and we'll flag the places where AXL differs from the Starlark you already know.

## Prerequisites

* **Git** and a terminal.

* **Bazelisk**, so `.bazelversion` is honored. See [installing Bazel](/learning/bazel-101/installing).

* **The Aspect CLI.** One line, no account needed:

  ```shell theme={null}
  curl -fsSL https://install.aspect.build | bash
  ```

  See [How to install the Aspect CLI](/docs/cli/install) for Homebrew, npm, and the `tools/bazel` wrapper.

* Roughly 2 GB of disk for the Bazel output base, and a network connection for the first build.

Everything in this course is free and open source. An Aspect account unlocks the CI integrations in the last two modules, and it's also free. We cover that when we get there.

## Course contents

<Columns cols={2}>
  <Card title="Why AXL" icon="circle-question" href="/learning/aspect-160/why">
    The glue layer every monorepo grows, why it's always Bash, and what changes when the outside of Bazel gets an extension language.
  </Card>

  <Card title="Set up the lab" icon="download" href="/learning/aspect-160/setup">
    Clone a starter repo, pin the CLI version, and run the built-in tasks so you know what "working" looks like.
  </Card>

  <Card title="Your first task" icon="terminal" href="/learning/aspect-160/first-task">
    Write a task, give it typed arguments, run a subprocess, read the environment, and return a verdict.
  </Card>

  <Card title="Driving Bazel" icon="gear" href="/learning/aspect-160/bazel">
    Query the graph, build and test targets, and consume the Build Event Stream as it arrives.
  </Card>

  <Card title="Configuring the CLI" icon="sliders" href="/learning/aspect-160/config">
    <code>config.axl</code>: flags, task defaults, aliases, traits, features, lifecycle hooks, and tips.
  </Card>

  <Card title="BUILD file generation" icon="wand-magic-sparkles" href="/learning/aspect-160/generators">
    Teach Gazelle your conventions in Starlark, including resolving imports to labels across packages.
  </Card>

  <Card title="Reporting into CI" icon="code-pull-request" href="/learning/aspect-160/ci">
    Status checks, a live PR summary, inline lint findings with one-click fixes, and a surface of your own.
  </Card>

  <Card title="Connect an account" icon="cloud" href="/learning/aspect-160/cloud">
    What an Aspect account turns on: the VCS integrations, a remote cache, the Build and Test UI, and build results over MCP.
  </Card>

  <Card title="Where to go next" icon="signs-post" href="/learning/aspect-160/next">
    Shipping AXL to other repos, the reference docs, and how to get help.
  </Card>
</Columns>

## Running this as a 90-minute workshop

The nine modules are sized for a single session, with the three headline exercises (a subcommand, a generator, a CI integration) weighted heaviest:

| Module                        | Minutes | Running total |
| ----------------------------- | ------- | ------------- |
| Why AXL                       | 5       | 0:05          |
| Set up the lab                | 5       | 0:10          |
| Your first task               | 15      | 0:25          |
| Driving Bazel                 | 15      | 0:40          |
| Configuring the CLI           | 10      | 0:50          |
| BUILD file generation         | 15      | 1:05          |
| Reporting into CI             | 20      | 1:25          |
| Account, and where to go next | 5       | 1:30          |

Every module ends with the complete file, so anyone who falls behind can paste and catch up at the next section boundary.

<Note>
  Run the setup module before the session if you can. The first Bazel build downloads a toolchain, a prebuilt Gazelle, and ShellCheck, which is the one part of this course that conference WiFi can make miserable.
</Note>