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

# A project with one file

> Pin the Aspect CLI in a repository and explore its task surface before any Bazel workspace exists.

Clone the lab repository and start at the beginning:

```shell theme={null}
git clone https://github.com/gregmagolan/extending-bazel-with-starlark.git
cd extending-bazel-with-starlark
git checkout step-0
```

<Note>
  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.
</Note>

Look at what's here:

```shell theme={null}
find . -path ./.git -prune -o -type f -print
```

```text theme={null}
./.aspect/version.axl
```

One file. That's the whole project.

```python title=".aspect/version.axl" theme={null}
version("2026.41.50")
```

## The pin works

```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"
    },
    ...
```

Thirty-three commands:

```shell theme={null}
aspect describe | jq '.commands | length'
```

```text theme={null}
33
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.