Skip to main content

cli_args

bool​

def bool(
default = False,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Accepts "true" or "false" from cli, and gets a bool in bxl. Defaults to false if no explicit default is provided.

Examples​

Declaration:

cli_args = {
    "verbose": cli_args.bool(),         # defaults to false
    "dry_run": cli_args.bool(True),     # defaults to true
}

CLI usage:

buck2 bxl //my.bxl:target -- --verbose true

configured_target_expr​

def configured_target_expr(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from the cli, and treats it as a target pattern. The target can be configured using either ?modifier syntax or --modifier flag, in addition to --target-platforms flag. Resolves the pattern and returns a list of ConfiguredTargetLabel in bxl.

Examples​

Declaration:

cli_args = {
    "targets": cli_args.configured_target_expr(),
}

CLI usage (accepts patterns like cell//foo:bar, cell//foo:, or cell//foo/...):

buck2 bxl //my.bxl:target -- --targets cell//package:rule?cell//config:platform

configured_target_label​

def configured_target_label(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets a parsed ConfiguredTargetLabel in bxl. The target can be configured using either ?modifier syntax or --modifier flag, in addition to --target-platforms flag.

Examples​

Declaration:

cli_args = {
    "target": cli_args.configured_target_label(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --target cell//package:rule?cell//config:platform

enum​

def enum(
variants: list[str] | tuple[str, ...],
/,
default = ...,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes a set of defined values in variants, and gets a str in bxl. Only the specified variant strings are accepted; any other value is an error.

Examples​

Declaration:

cli_args = {
    "mode": cli_args.enum(["debug", "release"]),
}

CLI usage:

buck2 bxl //my.bxl:target -- --mode debug

float​

def float(
default = ...,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets a float in bxl.

Examples​

Declaration:

cli_args = {
    "threshold": cli_args.float(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --threshold 3.14

int​

def int(
default = ...,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets an int in bxl.

Examples​

Declaration:

cli_args = {
    "count": cli_args.int(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --count 42

json​

def json(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, parses it as a JSON string, and returns the parsed object in bxl.

Note: Does not accept a file path. Use cli_args.json_file() to read JSON from a file.

Examples​

Declaration:

cli_args = {
    "config": cli_args.json(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --config '{"key": "value", "count": 3}'

json_file​

def json_file(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, reads the specified file as JSON, and returns the parsed object in bxl. Supports both relative and absolute paths. Relative paths are resolved relative to the buck project root.

Examples​

Declaration:

cli_args = {
    "config": cli_args.json_file(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --config path/to/config.json

list​

def list(
inner: bxl.CliArgs,
/,
default = ...,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes a list of args from cli, and gets a list of the inner type in bxl.

Examples​

Declaration:

cli_args = {
    "numbers": cli_args.list(cli_args.int()),
    "names": cli_args.list(cli_args.string()),
}

Multiple values can be passed either as space-separated values after a single flag, or by repeating the flag. Both styles produce the same result and can be mixed:

buck2 bxl //my.bxl:target -- --numbers 1 2 3
buck2 bxl //my.bxl:target -- --numbers 1 --numbers 2 --numbers 3

Both invocations above yield [1, 2, 3] in ctx.cli_args.numbers.

option​

def option(
inner: bxl.CliArgs,
doc: str = "",
default = None,
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets the inner type in bxl. If not given, will get None in bxl.

Examples​

Declaration:

cli_args = {
    "message": cli_args.option(cli_args.string()),
    "limit": cli_args.option(cli_args.int()),
}

CLI usage (omitting the flag yields None in bxl):

buck2 bxl //my.bxl:target -- --message "hello"

string​

def string(
default = ...,
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets a string in bxl.

Examples​

Declaration:

cli_args = {
    "name": cli_args.string(),
    "greeting": cli_args.string("hello"),  # with default
}

CLI usage:

buck2 bxl //my.bxl:target -- --name foo

sub_target​

def sub_target(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets a parsed ProvidersLabel in bxl.

Note: this will not check if the target is valid.

Examples​

Declaration:

cli_args = {
    "provider": cli_args.sub_target(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --provider cell//package:rule[subtarget]

sub_target_expr​

def sub_target_expr(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and treats it as a sub target pattern. Resolves the pattern and returns a list of ProvidersLabel in bxl.

Examples​

Declaration:

cli_args = {
    "targets": cli_args.sub_target_expr(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --targets cell//package:rule[subtarget]

target_expr​

def target_expr(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from the cli, and treats it as a target pattern. Resolves the pattern and returns a list of TargetLabel in bxl.

Examples​

Declaration:

cli_args = {
    "targets": cli_args.target_expr(),
}

CLI usage (accepts patterns like cell//foo:bar, cell//foo:, or cell//foo/...):

buck2 bxl //my.bxl:target -- --targets cell//package/...

target_label​

def target_label(
doc: str = "",
*,
short = ...,
) -> bxl.CliArgs

Takes an arg from cli, and gets a parsed TargetLabel in bxl.

Note: this will not check if the target is valid.

Examples​

Declaration:

cli_args = {
    "target": cli_args.target_label(),
}

CLI usage:

buck2 bxl //my.bxl:target -- --target cell//package:rule