> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.
# Setting up the course repository
> Clone the lab repository, start its build warming, and meet the pinned Aspect CLI you'll extend for the rest of the course.
Clone the lab repository and check out the first step:
```shell theme={null}
git clone https://github.com/gregmagolan/extending-bazel-with-starlark.git
cd extending-bazel-with-starlark
git checkout step-1
```
Every section of this course starts with a `git checkout`. Typing the AXL out yourself is optional — 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.
## Start the build now
Before you read any further. This is the biggest download in the course, and almost none of it is your code: Bazelisk downloads Bazel 9.3.0 first (about 70 MB, pinned in `.bazelversion`), then Bazel fetches `rules_go`, `gazelle` and the Go SDK 1.25.1 (about 58 MB), one after another.
```shell theme={null}
bazel test //...
```
`aspect test //...` works too.
Expect roughly **70 seconds** the first time on a machine that has never built this — most of it fetching `rules_go` and the Go SDK, not compiling your code. Once those are cached it is about **25 seconds** from clean, and **under a second** when nothing has changed. The bulk of the cold compile is `rules_go` building the Go standard library: one large action that never runs again, and you'll see it by name later when you ask the build what it spent its time on.
Leave it running and read on — nothing before `aspect changed` needs the build finished.
## What you cloned
A Go monorepo with 55 libraries, 55 tests and 3 binaries:
```text theme={null}
lib/ clock codec schema validate log metrics retry
config auth store ratelimit queue api
internal/domain/ 39 packages
cmd/ server worker cron
```
The layering is the part that matters, and it is deliberate. `lib/clock`, `lib/codec`, `lib/schema` and `lib/validate` are stdlib-only and sit at the bottom. `lib/log` is above them and nearly everything is above *it*. Of the 39 domain packages, 18 are pure models that never touch logging, and 21 are wired into `lib/log`, `lib/metrics` and `lib/store`.
That shape exists so that the questions you ask in the next few sections have non-obvious answers. A repository where everything depends on everything teaches nothing about dependency queries.
There is a deliberately flaky test in `internal/domain/forecast`. It fails about one run in three, it is marked as intentional in the source, and it is there for a later section about catching flakes. If `bazel test //...` goes red on `forecast_test`, that is the course working as designed — run it again.
## The pin works
One more file arrived with the repository, and it is the one that decides which CLI you are running:
```python title=".aspect/version.axl" theme={null}
version("2026.41.50")
```
```shell theme={null}
aspect version
```
```text theme={null}
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
```shell theme={null}
aspect help
```
```text theme={null}
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
```shell theme={null}
aspect describe
```
```json theme={null}
{
"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"
},
...
```
Next: the first command.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.