args - Aspect Build

type Args function string_list

def string_list(
*,
required: bool = False,
default: None | list[str] = None,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines a string list flag that can be specified multiple times. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function uint_list

def uint_list(
*,
required: bool = False,
default: None | list[int] = None,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines an unsigned integer list flag that can be specified multiple times. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function trailing_var_args

def trailing_var_args(
*,
description: None | str = None
) -> args.Arg

Defines a trailing variable argument that captures the remaining arguments without further parsing. Only one such argument is permitted, and it must be the last in the sequence. function boolean

def boolean(
*,
required: bool = False,
default: bool = …,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines a boolean flag. Use --flag_name (true) or --flag_name=false. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function int

def int(
*,
required: bool = False,
default: int = …,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines an integer flag. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function uint

def uint(
*,
required: bool = False,
default: int = …,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines an unsigned integer flag. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function int_list

def int_list(
*,
required: bool = False,
default: None | list[int] = None,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines an integer list flag that can be specified multiple times. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function custom

def custom(
typ: typing.Any,
/,
*,
default: typing.Any = …,
description: None | str = None
) -> args.Arg

Defines a config-only arg — not exposed on the CLI. Set via config.axl only. The type argument must be a built-in or otherwise frozen type (e.g. str, int, bool, list[str]). If provided, default must match the declared type. Example:

my_task = task(
    implementation = _impl,
    args = {
        "mode": args.string(default = "auto"),
        "bucket": args.custom(str | None, default = None),  # config.axl only
    },
)

function string

def string(
*,
required: bool = False,
default: str = …,
short: None | str = None,
long: None | str = None,
values: None | list[str] = None,
description: None | str = None,
bare: None | str = None,
config_only: bool = False
) -> args.Arg

Defines a string flag that can be specified as --flag_name=flag_value. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps the arg off the command line entirely: it is then settable only from config.axl, for a value a task reads but nobody should type. Every flag-shaped constructor takes it, and it cannot be combined with required, short or long, which name or demand a command-line spelling that does not exist. args.custom(type, ...) is config-only by construction and so has no such parameter; the argv-shaped kinds (positional, trailing_var_args, passthrough) have none either, since their content comes from the command line. bare = "value" additionally makes a valueless --flag_name legal, resolving to value — for a flag whose common case needs no argument (--remote meaning “the usual capabilities”). Without it, omitting the value is an error. bare and default are independent, so a flag can distinguish “absent” from “passed with no value”. function boolean_list

def boolean_list(
*,
required: bool = False,
default: None | list[bool] = None,
short: None | str = None,
long: None | str = None,
description: None | str = None,
config_only: bool = False
) -> args.Arg

Defines a boolean list flag that can be specified multiple times. Use long = "override-name" to override the default kebab-case derivation. config_only = True keeps it off the command line (see args.string). function passthrough

def passthrough(
*,
position: str,
value_flags_from: None | str = None,
description: None | str = None
) -> args.Arg

Defines a bucket that collects the flags this task does not declare, instead of failing the parse with “unexpected argument”. For a task that wraps another tool (bazel, cargo, …) and wants that tool’s own flags to work without being individually redeclared or wrapped. position selects which side of the task name a flag is collected from:

"pre_command" — before it: aspect --output_base=/tmp build. This is where Bazel takes its startup options.
"post_command" — after it: aspect build --remote_download_all.

A task may declare one bucket per position; both are lists of strings in command-line order. Keeping them separate is what lets a task forward each set to the slot it was typed for. value_flags_from names a sibling args.string_list of the flags that take a separate value, so -c opt is collected as a pair. Without it — or for a flag the list omits — the token after a collected flag is left alone, since the arity of a flag nobody declared is unknowable: --jobs 8 would collect --jobs and leave 8 as a positional. Keeping the list in a sibling arg rather than inline is what lets config.axl replace it. Nothing is rewritten on the way through: what the wrapped tool receives is what was typed. Read a bucket with ctx.args.claim(name), which both returns the list and tells the runtime this task is responsible for those flags. Buying out of the “unexpected argument” error is only sound if something acts on what was collected, so the runtime refuses to spawn the wrapped tool while a bucket is unclaimed, and fails the run if any bucket still holds flags when the task returns. Reading the value as a plain attribute is inspecting, not forwarding — claim before you run anything. A path that deliberately runs nothing can claim to say so. Example:

def _impl(ctx):
    tool_flags = ctx.args.claim("tool_flags")
    return ctx.std.process.command("some-tool").args(tool_flags).spawn().wait().code

my_task = task(
    implementation = _impl,
    args = {
        "targets": args.positional(minimum = 1, maximum = 512),
        "tool_flags": args.passthrough(position = "post_command"),
    },
)

function positional

def positional(
*,
minimum: int = 0,
maximum: int = 1,
default: None | list[str] = None,
description: None | str = None
) -> args.Arg

Defines a positional argument that accepts a range of values.