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

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 used by the CLI, keeping the description aligned with the accepted arguments. 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. If you run aspect describe cache diff without quotes, the command reports the extra argument as an error.

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 with a copy-pasteable command string, its group path, one-line summary, and defining module. Use it to discover what’s available before drilling into a specific task:

$ aspect describe | jq '.tasks[] | select(.command | startswith("cache"))'
{
  "command": "aspect cache diff",
  "group": ["cache"],
  "kind": "diff",
  "summary": "List test targets affected by the current tree vs. the remote cache.",
  "module": "@aspect//cache/diff.axl"
}

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

Passing a command string returns the same header plus every flag it accepts, with type, default, allowed values, and description. Feature flags accepted everywhere are included too:

$ aspect describe 'cache diff' | jq '.flags[] | {name, type, default, description}'
{
  "name": "--mode",
  "type": "string",
  "default": "overreport",
  "description": "How to attribute cache misses to affected test targets."
}
{
  "name": "--output",
  "type": "string",
  "default": "lines",
  "description": "Output format: 'lines' (one label per line) or 'json'."
}
...

`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",
  "type": "int",
  "default": 2,
  "default_from_config": true,
  "description": "..."
}

This makes describe a reliable way to determine a command’s default behavior in the current repository.

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": {
    "logged_in": true,
    "status": "ok",
    "identity": "you@example.com",
    "login_command": "aspect auth login"
  },
  "deployments": [
    {
      "name": "example",
      "logged_in": false,
      "status": "expired",
      "identity": null,
      "endpoints": { "api": "https://api.example.aspect.build" },
      "login_command": "aspect auth login --deployment=example"
    }
  ],
  "default_deployment": "example"
}

Each entry includes logged_in, status, identity, its endpoints, and the exact login_command that re-authenticates it. A caller that finds an expired token gets the remedy without additional lookups. Only the JSON goes to stdout. The task header stays on stderr, so you can pipe stdout cleanly to jq or a file. Text output is unchanged.

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

Read commands use --output for their format switch. aspect cache diff now documents --output as the spelling for its format flag. 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

Use aspect --help as a useful first call for both 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 cache diff wrapper install, uninstall
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. Interactive terminals and CI retain their existing progress behavior.
aspect feature strips ANSI escape codes when its output isn’t a terminal and honors NO_COLOR.

When to use which command

I want to…	Use
List every task available in this repo	`aspect describe` (index) or `aspect --help`
See one task’s full flag detail	`aspect describe '<command>'`
Know the effective default for a flag in this repo	`aspect describe '<command>'` — 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`

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 '.tasks[] | 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 '.flags[] | select(.name == "--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.status')" != "ok" ]; then
  cmd=$(echo "$status" | jq -r '.account.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

​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

When to use which command

Example: driving `aspect` from a script

Example: an agent recovering from an auth failure

See also