A project with one file

Clone the lab repository and start at the beginning:

git clone https://github.com/gregmagolan/extending-bazel-with-starlark.git
cd extending-bazel-with-starlark
git checkout step-0

Every section of this course starts with a git checkout. You are not going to type AXL from a tutorial — you’ll check out the code, read the diff that brought it, run it, and change one thing. If you fall behind at any point, check out the next step and carry on.Leave your main alone. Every step branch is an ancestor of main, and the commands you’ll run default to --base=main, so git merge-base HEAD main resolves to the step you’re standing on and a clean tree reports nothing changed. Reset or move main and those defaults start diffing against the wrong commit — which looks like a broken task rather than a moved branch.

Look at what’s here:

find . -path ./.git -prune -o -type f -print

./.aspect/version.axl

One file. That’s the whole project.

.aspect/version.axl

version("2026.41.50")

The pin works

aspect version

2026.41.50

No download this time, and no “latest” — the launcher read the repository’s pin and ran that exact CLI. Everyone who clones this repository gets the same one.

What’s available

aspect help

Aspect CLI v2026.41.50 — https://aspect.build/docs/cli

Aspect's programmable task runner built on top of Bazel
{ Correct, Fast, Usable } -- Choose three

Usage: aspect [TASK|GROUP|COMMAND]

Tasks:
  build         Build Bazel targets. Wraps `bazel build` with retries, remote cache/BES wiring, and CI status reporting.
  delivery      Build and deliver binary targets. Targets are built with stamping and delivered exactly once per commit unless forced; change detection skips targets whose outputs haven't changed since the last delivery.
  format        Format source files with the configured formatter target. Formats changed files by default; `--scope=all` for the whole tree.
  gazelle       Generate and update BUILD files with gazelle. Applies the patch locally; detect-only on CI (`--check-only`).
  gc            Reclaim Bazel output bases and download-cache entries nothing is using.
  init          Scaffold a new Bazel project from the Aspect Workflows template.
  lint          Lint targets using rules_lint aspects and report findings on the terminal or as code-review comments.
  mcp           Serve build results to AI agents over MCP
  output-bases  List the Bazel output bases on this machine: state, Bazel server memory, git branch, workspace and size.
  run           Build a target with bazel and run the resulting binary.
  test          Run Bazel tests. Wraps `bazel test` with retries, remote cache/BES wiring, and CI status reporting.

Task Groups:
  auth      configure, login, logout, remove, status, use
  axl       add
  cache     diff
  ci        bazelrc, runner-health-check, runner-metadata, warming
  github    token
  setup     bazelrc, tools-bazel-wrapper, workspace-data
  worktree  add, inspect, list, path, prune, release

Commands:
  describe  Print the resolved task, flag and feature surface as JSON
  feature   List features and their flags
  version   Print version
  help      Print this message or the help of the given subcommand(s)

Options:
  -v, --version  Print version
  -h, --help     Print help

The same thing, for machines

aspect describe

{
  "aspect_cli_version": "2026.41.50",
  "commands": [
    {
      "command": "aspect auth configure",
      "summary": "Configure an Aspect Workflows deployment"
    },
    {
      "command": "aspect auth login",
      "summary": "Log in to Aspect Cloud or an Aspect Workflows deployment"
    },
    ...

Thirty-three commands:

aspect describe | jq '.commands | length'

Notice what isn’t here

There is no MODULE.bazel. No BUILD.bazel. No workspace, no targets, nothing to build — and bazel has never run in this directory. Yet the CLI has a task surface, that surface has help text, and it will hand you the whole thing as JSON on request. The thing you’re about to extend is programmable before your build exists. Hold onto describe. By the end of this course the commands you write will show up in that JSON — with their flags, their types and their defaults — and the last section is about who reads it. Next: a repository with an actual build in it.

​The pin works

​What’s available

​The same thing, for machines

​Notice what isn’t here

The pin works

What’s available

The same thing, for machines

Notice what isn’t here