Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Defining Arguments

Positional Arguments

Positional arguments are matched by order, not by name. They do not start with - or --.

command.add_argument(Argument("pattern", help="Search pattern").positional().required())
command.add_argument(Argument("path",    help="Search path").positional().default["."]())
myapp "hello" ./src
#       ↑        ↑
#     pattern   path

Positional arguments are assigned in the order they are registered with add_argument(). If fewer values are provided than defined arguments, the remaining ones use their default values (if any). If more are provided, an error is raised (see Positional Argument Count Validation).

Retrieving:

var pattern = result.get_string("pattern")  # "hello"
var path    = result.get_string("path")     # "./src"

Long Options

Long options start with -- and can receive a value in two ways:

SyntaxExampleDescription
--key value--output result.txtSpace-separated value.
--key=value--output=result.txtEquals-separated value.
command.add_argument(Argument("output", help="Output file").long["output"]())
myapp --output result.txt
myapp --output=result.txt

Both forms produce the same result:

result.get_string("output")  # "result.txt"

Short Options

Short options use a single dash followed by a single character.

command.add_argument(
    Argument("output", help="Output file").long["output"]().short["o"]()
)
myapp -o result.txt          # space-separated
myapp -oresult.txt           # attached value (see §9)

A short name is typically defined alongside a long name, but can also be used alone.

Compile-time validation. Both .long["x"]() and .short["x"]() accept a StringLiteral parameter. .short enforces that the name is exactly one character; .long enforces that the name is non-empty and does not start with -. Invalid names are caught at compile time — the program will not compile.

Boolean Flags

A flag is a boolean option that takes no value. It is False by default and becomes True when present.

command.add_argument(
    Argument("verbose", help="Enable verbose output")
    .long["verbose"]().short["v"]().flag()
)
myapp --verbose    # verbose = True
myapp -v           # verbose = True
myapp              # verbose = False (default)

Retrieving: (Flags)

var verbose = result.get_flag("verbose")  # Bool

Default Values

When an argument is not provided on the command line, its default value (if any) is used.

command.add_argument(
    Argument("format", help="Output format")
    .long["format"]().short["f"]().default["table"]()
)
command.add_argument(
    Argument("path", help="Search path").positional().default["."]()
)
myapp "hello"                # format = "table", path = "."
myapp "hello" --format csv   # format = "csv",   path = "."
myapp "hello" ./src          # format = "table", path = "./src"

Works for every kind of argument, and the default always lands where that argument’s own accessor reads it:

Argument kindDefault is read back withExample
plain optionget_string() / get_int().default["table"]()
positionalget_string().default["."]()
.flag()get_flag().default["true"]()
.count()get_count().default["2"]()
.append()get_list().default["x"]()
.map_option()get_map().default["A=1"]()

A default that does not fit its argument is rejected when you call add_argument(), rather than when your user runs the program. A .flag() default must be a boolean literal (true/false, 1/0, yes/no, on/off); a .count() default must be an integer; a .map_option() default must be in key=value form; and if the argument has .choice[](), the default must be one of those choices.

Keep in mind that a default is not user input. was_provided() returns False for it, and it never satisfies a group constraint on its own — though it does satisfy .required() on the argument that carries it.

Required Arguments

Mark an argument as required to make parsing fail when it is absent.

command.add_argument(
    Argument("pattern", help="Search pattern").positional().required()
)
myapp "hello"   # OK
myapp           # Error: Required argument 'pattern' was not provided

Typically used for positional arguments. Named options can also be marked required.

Aliases

Register alternative long names for an argument with .alias[](). The alias is validated at compile time (same rules as .long[](): not empty, no - prefix, no =). Chain multiple calls for several aliases.

.alias[]() was called .alias_name[]() until Mojo v1.1.0 freed the alias keyword, and the alias= parameter of Option, Flag and Count was called alias_name=. The old spellings were deprecated in ArgMojo v0.9.0 and removed in v0.10.0; replace .alias_name[ with .alias[ and alias_name= with alias=.

command.add_argument(
    Argument("colour", help="Colour theme")
        .long["colour"]()
        .alias["color"]()
)
myapp --colour red     # OK — colour = "red"
myapp --color  red     # OK — resolved via alias, colour = "red"

Prefix matching applies to aliases as well. When both the primary name and an alias share a prefix, _find_by_long deduplicates so the match is never ambiguous within a single argument.

Multiple aliases are supported by chaining:

command.add_argument(
    Argument("output", help="Output format")
        .long["output"]()
        .alias["out"]().alias["fmt"]()
)