args_argv()

def args_argv() -> list

Returns the full command-line arguments (argv) passed to the script.

This returns the complete argv list including argv[0] (the program name). Use args_program() to get just the program name, or args_argv()[1:] to get arguments without the program name.

Returns

A list of strings representing command-line arguments. First element is typically the program name, followed by arguments. Empty list if no arguments provided.

args_flag()

def args_flag(name, short, help) -> dict

Creates a boolean flag option descriptor.

Flags are boolean options that are either present or absent. They don’t take values. When present on the command line, the flag is set to True. When absent, it defaults to False.

Raises: Error: If name doesn’t start with “–” or contains invalid characters Error: If short is provided but doesn’t start with “-” Error: If short is not a single character after the dash

Args

• name: string: The long flag name, must start with “–” and contain only lowercase letters, digits, and hyphens. Examples: “–verbose”, “–dry-run”, “–force”
• short: Optional single-character short flag, must start with “-” if provided. Examples: “-v”, “-d”, “-f”. If empty, no short flag is available.
• help: Optional help text describing what the flag does. Will be shown in usage output. Keep descriptions concise and clear.

Returns

A flag descriptor (dictionary) to be used in parser specs. Internal structure: {“kind”: “flag”, “long”: name, “short”: short_value, “help”: help_text, “default”: False}

args_list()

def args_list(name, short, help, choices, type) -> dict

Creates a repeatable option descriptor.

Lists are options that can appear multiple times on the command line. Each occurrence adds a value to the resulting list. Useful for collecting multiple values like multiple tags, files, or includes.

Raises: Error: If name doesn’t start with “–” or contains invalid characters Error: If short is provided but doesn’t start with “-” Error: If type is not one of “str”, “int”, “bool”

Args

• name: string: The long option name, must start with “–” and contain only lowercase letters, digits, and hyphens. Examples: “–tag”, “–include”, “–file”
• short: Optional single-character short option. Examples: “-t”, “-i”, “-f”
• help: Optional help text. Suggestion: mention that option is repeatable. Example: “Include a tag (can be used multiple times)”
• choices: Optional list of allowed values. Each occurrence must use an allowed choice. Note: choices are only supported when type=“str” (the default); combining choices with type=“int” or type=“bool” raises an error.
• type: string: The value type: “str” (default), “int”, or “bool”. Determines how each value is parsed.

Returns

A list descriptor (dictionary) for use in parser specs. Default value is always an empty list [].

args_opt()

def args_opt(name, short, help, default, choices, type) -> dict

Creates a single-value option descriptor.

Options take a value that can be passed on the command line. Each option can appear at most once (unlike lists which can repeat). Supports different value types and optional constraints like choice restrictions.

Raises: Error: If name doesn’t start with “–” or contains invalid characters Error: If short is provided but doesn’t start with “-” Error: If type is not one of “str”, “int”, “bool” Error: If default value doesn’t match the specified type

Args

• name: string: The long option name, must start with “–” and contain only lowercase letters, digits, and hyphens. Examples: “–env”, “–output”, “–config-file”
• short: Optional single-character short option. Examples: “-e”, “-o”, “-c”
• help: Optional help text describing the option. Shown in usage output.
• default: Default value if the option is not provided on command line. Type depends on the type parameter. If None, uses type-specific default.
• choices: Optional list of allowed values. If provided, only these values are accepted. Example: [“dev”, “staging”, “prod”]. If empty list or None, any value is allowed.
• type: string: The value type: “str” (default), “int”, or “bool”. Determines how the value is parsed and what default is used if not provided. When type=“bool”, the command-line value must be one of: true/1/yes/on (True) or false/0/no/off (False).

Returns

An option descriptor (dictionary) for use in parser specs. Internal structure includes all parameters for option validation and parsing.

args_parse()

def args_parse(spec) -> dict

Parses command-line arguments according to a parser specification.

This is the main function that performs argument parsing. It processes argv[1:] according to the parser spec, validating values and assigning defaults.

Special behavior: - If –help or -h is encountered, prints usage and exits with code 0 - If parsing fails (missing required args, invalid values, etc.), prints usage message and error details, then exits with code 2 - Options and positionals are collected into a result dictionary

Raises: Error: This function handles errors by printing and exiting rather than raising exceptions. Help requests trigger exit 0, parse errors trigger exit 2.

Args

• spec: dict: A parser specification created with args_parser().

Returns

A dictionary mapping argument names to their parsed values. - Flag names map to boolean values (True/False) - Option names map to their values (as strings, ints, or bools per type) - List option names map to lists of values - Positional names map to their values or lists (if variadic)

args_parser()

def args_parser(name, description, options, positional) -> dict

Creates a parser specification.

A parser specification defines the complete structure of command-line arguments, including all supported options and positional arguments. Use with args_parse() to actually parse command-line arguments.

Args

• name: string: Name of the program/command. Used in help text.
• description: string: Description of what the program does. Shown at top of help text.
• options: List of option descriptors created with args_flag(), args_opt(), or args_list(). Default is empty list (no options).
• positional: List of positional descriptors created with args_pos(). Default is empty list (no positional arguments). Variadic positional must come last.

Returns

A parser specification (dictionary) to be passed to args_parse().

args_pos()

def args_pos(name, required, variadic) -> dict

Creates a positional argument descriptor.

Positional arguments are values provided on the command line after all options. They’re matched by position, not by flag name. Examples: in “command source dest”, “source” and “dest” are positional.

Raises: Error: If name is empty or contains only whitespace

Args

• name: string: The name of the positional argument. Used in parsed results and help text. Examples: “source”, “destination”, “targets”, “pattern”
• required: bool: If True, the argument must be provided or parsing fails. Default False allows the argument to be optional. When False and the argument is not provided, its value in the parsed result is None.
• variadic: bool: If True, this positional consumes all remaining arguments (like *args). Only one positional can be variadic, and it must be the last one. Default False means the positional takes exactly one value.

Returns

A positional descriptor (dictionary) for use in parser specs. Internal structure: {“name”: name, “required”: required, “variadic”: variadic}

args_program()

def args_program() -> string

Returns the program name (argv[0]).

Returns the first element of argv, which is typically the name of the script or program being executed. Returns empty string if argv is empty (rare edge case).

Returns

The program name as a string. Usually ends with “.star” for Starlark scripts. Returns empty string if no program name available.