Drive the CLI from scripts and AI agents

The Aspect CLI surface can vary by repository. In addition to built-in tasks, aspect <task> runs tasks declared in your .aspect/*.axl files. The CLI provides a machine-readable view of the tasks, flags, and defaults available in the current workspace, along with structured output for other read-only commands used in automation. Use the features on this page when:

You’re writing a shell script or CI job that needs to enumerate tasks or flags without parsing help text.
You’re driving aspect from an AI coding agent that needs to discover commands, inspect a task’s flags on demand, and recover from errors without relying on prior knowledge.
You’re piping aspect output to a log, another process, or a file and need clean output without interactive progress updates or ANSI escape codes.
You want an AI agent to read your team’s build and test results directly, using the aspect mcp server.

Discover the surface with `aspect describe`

aspect describe prints the resolved CLI surface as JSON on stdout. It includes built-in and custom .axl tasks, the flags each task accepts, and the effective defaults after config.axl is applied. Flag names come from the same definitions the CLI parses. Start with the command index, then request full details for a specific task when needed:

aspect describe                    # command index with summaries
aspect describe 'cache diff'       # full details for one task

Quote multi-word task paths as a single argument. Use to inspect the cache diff task. Without quotes, aspect describe cache diff fails with unexpected argument ‘diff’.

Both forms default to JSON on stdout and exit non-zero on an unknown command (aspect describe 'nope' fails), so scripts can rely on the exit status.

The index (`aspect describe`)

The index lists every reachable task under commands, each with a copy-pasteable command string and its one-line summary, plus the active feature names under features:

$ aspect describe | jq '.commands[] | select(.command | startswith("aspect cache"))'
{
  "command": "aspect cache diff",
  "summary": "List the test targets affected by the current working tree, diffed against the remote cache."
}

One task’s flags (`aspect describe '<command>'`)

Passing a command string returns that task’s command, path, name, summary, description, and defined_in module, plus an args list. Each arg has its name, CLI flag (null for positionals), type, default, allowed_values, and description. Feature flags aren’t included; list those with aspect feature <name>.

$ aspect describe 'cache diff' | jq '.args[] | select(.flag != null) | {flag, type, default}'
{
  "flag": "--mode",
  "type": "string",
  "default": "overreport"
}
{
  "flag": "--output",
  "type": "string",
  "default": "lines"
}
...

`config.axl` overrides show through as effective defaults

If your config.axl overrides a task’s default, describe reports the effective default that applies in the current repository. Overrides preserve their declared types, so an integer override reads 2, not ["2"], and include "default_from_config": true:

{
  "name": "jobs",
  "flag": "--jobs",
  "type": "int",
  "default": 2,
  "default_from_config": true,
  "description": "..."
}

Check auth state with `aspect auth status --output=json`

aspect auth status prints a human-readable summary by default. Pass --output=json for machine-readable data that scripts and agents can use to diagnose authentication problems without parsing the text output:

$ aspect auth status --output=json
{
  "account": [
    {
      "name": "aspect-cloud",
      "builtin": true,
      "default": false,
      "logged_in": true,
      "status": "expires in 7h 12m",
      "identity": "Jane Doe <you@example.com>",
      "display_name": "Jane Doe",
      "email": "you@example.com",
      "issuer": "...",
      "login_command": "aspect auth login",
      "api_token_env": "ASPECT_API_TOKEN"
    }
  ],
  "deployments": [
    {
      "name": "example",
      "builtin": false,
      "default": true,
      "logged_in": false,
      "status": "",
      "identity": "",
      "display_name": "",
      "email": "",
      "issuer": "...",
      "login_command": "aspect auth login --deployment example",
      "api_token_env": "ASPECT_API_TOKEN_EXAMPLE",
      "cache": "remote.example.aspect.build",
      "exec": "",
      "bes": "remote.example.aspect.build",
      "results_url": "https://app.example.aspect.build"
    }
  ],
  "default_deployment": "example",
  "ignored": []
}

account is a list holding the Aspect Cloud entry; deployments lists configured deployments. Each entry has logged_in, a status string describing the token’s expiry (expires in 2h 14m, expired, no expiry, or empty when logged out), the environment variable CI reads its token from (api_token_env), and the exact login_command that re-authenticates it. Deployment entries add their advertised cache, exec, and bes hosts and results_url. Only the JSON goes to stdout. The task header stays on stderr, so you can pipe stdout to jq or a file.

`--output` is the standard flag for machine-readable output

Read commands use --output for their format switch. For aspect cache diff, the older --format still works but prints a deprecation warning:

aspect cache diff --output=json    # documented spelling
aspect cache diff --format=json    # deprecated alias; still works, warns

See aspect cache diff for the full list of formats.

Pipe-safe help and output

aspect --help is a good first call for humans and agents:

Every built-in task, including build, format, gazelle, lint, and test, has a one-line summary in the top-level help.

Task groups list their members inline, so you can see what’s inside a group without a second --help call:

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

Long groups use … (+N more) to omit additional members.

aspect test --help cross-references aspect cache diff under the section on running only affected tests.

The launcher’s download progress and aspect feature output are also safe to capture:

For redirected output, the launcher emits concise progress updates instead of terminal redraws.
aspect feature strips ANSI escape codes when its output isn’t a terminal and honors NO_COLOR.

Give each task its own warm worktree

New and experimental. File bugs and suggestions to aspect-build/aspect-cli/issues.

An agent that works on several tasks needs a checkout per task, and git worktree add gives Bazel a path it has never seen — a cold build every time, plus an output base stranded on disk when the worktree goes. aspect worktree hands out worktrees from a pool of reused paths instead, so the Bazel state survives from one task to the next and N tasks cost one output base rather than N. The whole contract is two commands:

slot=$(aspect worktree add my-task-branch --create=origin/main --output=path) && cd "$slot"
# ... do the work ...
cd - >/dev/null   # back out first: releasing removes the slot directory
aspect worktree release my-task-branch

Use the two-step form. cd "$(aspect worktree add …)" returns 0 even when add fails, because the substitution is empty and cd "" is a no-op — the agent carries on in whatever directory it was already in, which is usually the main clone.

Refusals carry a stable error token under --output=json. Exit 75 (EX_TEMPFAIL) means the pool was busy for a moment — pool_busy while another call writes its bookkeeping, or branch_pending while another agent is mid-checkout on that branch — so retry. (Under --create, branch_pending exits 1: the branch will be the other agent’s, so pick another name.) slot_setting_up and reservation_lost carry retryable: true too and clear in moments; slot_warm, from prune, clears only after Bazel’s idle timeout. Anything else is a decision, not a wait.

Tell your agent about it

One line is enough, because the detail lives in a page the agent can read:

Never run `git worktree add` in this repo. Read
https://aspect.build/docs/cli/worktrees/agent-skill first.

Agent skill: pooled worktrees is written for an agent to follow, and names no flag defaults, so it does not go stale as the CLI moves. It also covers pasting the whole thing into AGENTS.md or saving it as a SKILL.md, if you would rather not depend on the agent fetching a page. The pool records which agent session took each slot, detected from CLAUDE_CODE_SESSION_ID and similar, or from ASPECT_AGENT_KIND / ASPECT_AGENT_ID for a harness that exports neither. See agent detection for the detection order and what aspect worktree list reports.

Serve build results to agents with `aspect mcp`

aspect mcp runs a Model Context Protocol server over stdio that gives AI tools such as Claude Code or Cursor read-only access to build and test results on an Aspect Workflows deployment: invocations, logs, targets, artifacts, and cross-invocation target statistics. Register it in your tool’s MCP configuration with "command": "aspect", "args": ["mcp"]. For prerequisites, multi-deployment setup, and the tool list, see Build results over MCP.

When to use which command

I want to…	Use
List every task available in this repo	`aspect describe` (index) or `aspect --help`
List the feature flags every task accepts	`aspect feature`, then `aspect feature <name>`
See one task’s full flag detail	`aspect describe '<command>'`
Know the effective default for a flag in this repo	`aspect describe '<command>'`, then check `default_from_config`
Diagnose an auth failure programmatically	`aspect auth status --output=json`
Get the exact command to re-authenticate	`login_command` field in `aspect auth status --output=json`
Get affected test labels for scripting	`aspect cache diff --output=json`
Let an agent read build and test results from Workflows	`aspect mcp` registered as an MCP server
Give an agent task its own warm checkout	`aspect worktree add <branch> --create=origin/main --output=path`
See which agent session holds which worktree	`aspect worktree list`

Example: driving `aspect` from a script

Enumerate every task, drill into one, and act on its flags:

#!/usr/bin/env bash
set -euo pipefail

# 1. Discover: does this repo have `cache diff`?
if ! aspect describe | jq -e '.commands[] | select(.command == "aspect cache diff")' > /dev/null; then
  echo "cache diff not available in this repo" >&2
  exit 1
fi

# 2. Drill: read its effective default for --mode.
mode=$(aspect describe 'cache diff' | jq -r '.args[] | select(.flag == "--mode") | .default')
echo "Default mode is: $mode"

# 3. Run: use the JSON output format.
aspect cache diff --output=json > affected.json

Example: an agent recovering from an auth failure

status=$(aspect auth status --output=json)
if [ "$(echo "$status" | jq -r '.account[0].logged_in')" != "true" ] ||
   [ "$(echo "$status" | jq -r '.account[0].status')" = "expired" ]; then
  cmd=$(echo "$status" | jq -r '.account[0].login_command')
  echo "Re-authenticate with: $cmd" >&2
  exit 1
fi

​Discover the surface with aspect describe

​The index (aspect describe)

​One task’s flags (aspect describe '<command>')

​config.axl overrides show through as effective defaults

​Check auth state with aspect auth status --output=json

​--output is the standard flag for machine-readable output

​Pipe-safe help and output

​Give each task its own warm worktree

​Tell your agent about it

​Serve build results to agents with aspect mcp

​When to use which command

​Example: driving aspect from a script

​Example: an agent recovering from an auth failure

​See also

Discover the surface with `aspect describe`

The index (`aspect describe`)

One task’s flags (`aspect describe '<command>'`)

`config.axl` overrides show through as effective defaults

Check auth state with `aspect auth status --output=json`

`--output` is the standard flag for machine-readable output

Pipe-safe help and output

Give each task its own warm worktree

Tell your agent about it

Serve build results to agents with `aspect mcp`

When to use which command

Example: driving `aspect` from a script

Example: an agent recovering from an auth failure

See also