> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.
# args
`type` [Args](/docs/axl/types/args/args)
`function` **string\_list**
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**
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**
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**
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**
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**
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**
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**
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:
```starlark theme={null}
my_task = task(
implementation = _impl,
args = {
"mode": args.string(default = "auto"),
"bucket": args.custom(str | None, default = None), # config.axl only
},
)
```
`function` **string**
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**
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**
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:
```starlark theme={null}
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**
Defines a positional argument that accepts a range of values.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.