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

Help & Display

Value Name

Value name overrides the placeholder text shown for a value in help output. Without it, the argument’s internal name is shown in angle brackets (e.g., <output>).

By default, custom value names are also wrapped in angle brackets, matching the convention used by clap, cargo, pixi, and git. To display a bare value name without brackets, pass wrapped=False as a compile-time parameter.

Libraries with similar support: argparse (metavar), clap (value_name), cobra (metavar), Click (metavar).

command.add_argument(
    Argument("output", help="Output file path")
    .long["output"]().short["o"]().value_name["FILE"]()
)
command.add_argument(
    Argument("max-depth", help="Maximum directory depth")
    .long["max-depth"]().short["d"]().value_name["N"]()
)

Help output (before):

  -o, --output <output>       Output file path
  -d, --max-depth <max-depth> Maximum directory depth

Help output (after .value_name() — wrapped by default):

  -o, --output <FILE>         Output file path
  -d, --max-depth <N>         Maximum directory depth

Unwrapped value name — pass False to suppress the angle brackets:

command.add_argument(
    Argument("point", help="A 3D coordinate")
    .long["point"]().number_of_values[3]().value_name["COORD", False]()
)
      --point COORD COORD COORD    A 3D coordinate

Value name is purely cosmetic — it has no effect on parsing.

Hidden Arguments

A hidden argument is fully functional but excluded from the --help output. Useful for internal, deprecated, or debug-only options.

command.add_argument(
    Argument("debug-index", help="Dump internal search index")
    .long["debug-index"]().flag().hidden()
)
myapp --debug-index    # Works — flag is set to True
myapp --help           # --debug-index does NOT appear in the help text

Typical use cases:

  • Internal debugging flags that end users shouldn’t need.
  • Features that are experimental or not yet stable.
  • Backward-compatible aliases you don’t want to advertise.

Deprecated Arguments

Mark an argument as deprecated with .deprecated["message"](). The argument still works normally, but a warning is printed to stderr when the user provides it.

command.add_argument(
    Argument("format_old", help="Legacy output format")
        .long["format-old"]()
        .deprecated["Use --format instead"]()
)
myapp --format-old csv
# stderr: Warning: '--format-old' is deprecated: Use --format instead
# parsing continues: format_old = "csv"

Short options also trigger the warning:

command.add_argument(
    Argument("compat", help="Compat mode")
        .long["compat"]().short["C"]().flag()
        .deprecated["Will be removed in 2.0"]()
)
myapp -C
# stderr: Warning: '-C' is deprecated: Will be removed in 2.0

Help display — deprecated arguments show the deprecation message in the help text:

options:
  --format-old <format_old>    Legacy output format [deprecated: Use --format instead]

Default-if-no-value

Use .default_if_no_value["value"]() to make an option’s value optional. When the option is present without an explicit value, the default-if-no-value is used. When an explicit value is provided (via = for long options, or attached for short options), that value is used instead.

.default_if_no_value() automatically implies .require_equals() for long options in the sense that = is required to attach an explicit value. A bare --key is still accepted and uses the default-if-no-value; --key value (space-separated) does not treat value as the argument to --key but leaves it to be parsed as a positional argument or another option. To supply an explicit value to the option itself, the user must write --key=value.

command.add_argument(
    Argument("compress", help="Compression algorithm")
    .long["compress"]()
    .short["c"]()
    .default_if_no_value["gzip"]()
)

Behaviour:

SyntaxValue
(omitted)not set (or default, if .default() is also used)
--compress"gzip" (default-if-no-value)
--compress=bzip2"bzip2" (explicit)
-c"gzip" (default-if-no-value)
-cbzip2"bzip2" (attached)

Combined with .default():

command.add_argument(
    Argument("compress", help="Compression algorithm")
    .long["compress"]()
    .default_if_no_value["gzip"]()
    .default["none"]()
)
# Not provided  → "none"  (default)
# --compress    → "gzip"  (default-if-no-value)
# --compress=xz → "xz"    (explicit)

Help display — the optional value is shown in brackets:

options:
      --compress[=<compress>]    Compression algorithm

With .value_name["ALGO"]():

options:
      --compress[=ALGO]          Compression algorithm

Require Equals Syntax

Use .require_equals() to force --key=value syntax. Space-separated --key value is rejected, which avoids ambiguity when values might start with -.

command.add_argument(
    Argument("output", help="Output file")
    .long["output"]()
    .short["o"]()
    .require_equals()
)

Behaviour: (Require-Equals)

SyntaxResult
--output=file.txt"file.txt" (OK)
--output file.txterror
--outputerror
-o file.txt"file.txt" (OK — short options are unaffected)

Help display — the = is shown in the help:

options:
  -o, --output=<output>    Output file

Combined with .default_if_no_value() — see Default-if-no-value above. When both are set, --key uses the default-if-no-value while --key=val uses the explicit value.

Argument Groups

By default, all options appear under a single “Options:” heading in --help. Use .group["name"]() to organise related arguments under their own section heading.

command.add_argument(
    Argument("host", help="Server hostname")
    .long["host"]().value_name["ADDR"]().group["Network"]()
)
command.add_argument(
    Argument("port", help="Server port")
    .long["port"]().short["P"]().group["Network"]()
)
command.add_argument(
    Argument("output", help="Output file path")
    .long["output"]().short["o"]().value_name["FILE"]().group["Output"]()
)
command.add_argument(
    Argument("verbose", help="Increase verbosity")
    .long["verbose"]().short["v"]().count()
)

Help output:

options:
  -v, --verbose              Increase verbosity
  -h, --help                 Show this help message

Network:
      --host <ADDR>    Server hostname
  -P, --port <port>    Server port

Output:
  -o, --output <FILE>    Output file path

Key behaviours:

  • Ungrouped arguments remain under “Options:”.
  • Group headings appear in first-appearance order after “Options:”.
  • Persistent arguments are collected under “Global Options:” regardless of their group.
  • Hidden arguments are excluded from all sections.
  • Column padding is computed independently per section, so each group aligns neatly.
  • Groups are purely cosmetic — they do not affect parsing or validation.

Auto-generated Help

Every command automatically supports --help (or -h or -?). The help text is generated from the registered argument definitions.

myapp --help
myapp -h
myapp '-?'     # quote needed: ? is a shell glob wildcard

Example output:

A CJK-aware text search tool

usage: myapp <pattern> [path] [OPTIONS]

arguments:
  pattern    Search pattern
  path       Search path

options:
  -l, --ling                        Use Lingming IME for encoding
  -i, --ignore-case                 Case-insensitive search
  -v, --verbose                     Increase verbosity (-v, -vv, -vvv)
  -d, --max-depth N                 Maximum directory depth
  -f, --format {json,csv,table}     Output format
      --color / --no-color          Enable colored output
  -?, -h, --help                    Show this help message
  -V, --version                     Show version

Help text columns are dynamically aligned: the padding between the option names and the description text adjusts automatically based on the longest option line, so everything stays neatly aligned regardless of option length.


Coloured Output

Help output uses ANSI colour codes by default to enhance readability.

ElementDefault styleANSI code
Section headersbold + underline + bright yellow\x1b[1;4m\x1b[93m
Program namebold magenta\x1b[1;35m
Short option namesbold green\x1b[1;32m
Long option namesbold cyan\x1b[1;36m
Value names / metavarbold yellow\x1b[1;33m
Positional arg namesbold green\x1b[1;32m
Subcommand namesbold cyan\x1b[1;36m
Deprecation warningsorange (dark yellow)\x1b[33m
Parse errorsbright red\x1b[91m
Description textdefault terminal colour—

The _generate_help() method accepts an optional color parameter:

var help_colored = command._generate_help()              # color=True (default)
var help_plain   = command._generate_help(color=False)   # no ANSI codes

Custom Colours

The header colour, argument-name colour, deprecation warning colour, and parse error colour are all customisable. Section headers always keep the bold + underline style; only the colour changes.

var command = Command("myapp", "My app")
command.header_color["BLUE"]()     # section headers in bright blue
command.argument_color["GREEN"]()       # ALL option/argument names in bright green
command.warn_color["YELLOW"]()     # deprecation warnings (default: orange)
command.error_color["MAGENTA"]()   # parse errors (default: red)

argument_color is a convenience that sets all six name-colour roles at once. For fine-grained control:

command.program_color["MAGENTA"]()       # program name in usage line
command.short_option_color["GREEN"]()    # short options (-h, -p)
command.long_option_color["CYAN"]()      # long options (--help, --port)
command.value_color["YELLOW"]()          # value names / metavar (PORT, <HOST>)
command.positional_color["GREEN"]()      # positional argument names
command.command_color["CYAN"]()          # subcommand names in commands section

Available colour names (uppercase only):

NameANSI codePreview
RED91bright red
GREEN92bright green
YELLOW93bright yellow
BLUE94bright blue
MAGENTA95bright magenta
PINK95alias for MAGENTA
CYAN96bright cyan
WHITE97bright white
ORANGE33orange/dark yellow

An unrecognised colour name is caught at compile time — the program will not compile if you pass an invalid name. Note that the colour name is a StringLiteral parameter and must be provided as a compile-time string literal (bracket-parameter form); dynamic runtime selection of colours is not supported by this API.

Padding calculation is always based on the plain-text width (without escape codes), so columns remain correctly aligned regardless of whether colour is enabled.

What controls the output:

Builder methodEffect on help
.help("...")Sets the description text for the option.
.value_name["X"]()Replaces the default placeholder (e.g., N, FILE).
.choice[]()Shows {a,b,c} in the placeholder.
.hidden()Completely excludes the option from help.
.required()Positional args show as <name> instead of [name].

After printing help, the program exits cleanly with exit code 0.


NO_COLOR Environment Variable

ArgMojo respects the NO_COLOR convention. When the NO_COLOR environment variable is set (any value, including an empty string), all ANSI colour codes are suppressed in:

  • Help output (_generate_help())
  • Warning messages (_warn())
  • Error messages (_error() and _error_with_usage())
NO_COLOR=1 myapp --help    # plain-text help, no colours
NO_COLOR= myapp --help     # also suppressed (empty string counts as "set")
myapp --help               # coloured output (NO_COLOR is unset)

This takes priority over the color=True default but does not override an explicit _generate_help(color=False) call (which already produces plain output regardless).


Show Help When No Arguments Provided

Use help_on_no_arguments() to automatically display help when the user invokes the command with no arguments (like git, docker, or cargo):

var command = Command("myapp", "My application")
command.add_argument(Argument("file", help="Input file").long["file"]().required())
command.help_on_no_arguments()
var result = command.parse()
myapp          # prints help and exits
myapp --file x # normal parsing

This is particularly useful for commands that require arguments — instead of showing an obscure “missing required argument” error, the user sees the full help text.

Custom Tips

Add custom tip lines to the bottom of your help output with add_tip(). This is useful for documenting common patterns, gotchas, or examples.

var command = Command("calc", "A calculator")
command.add_argument(Argument("expr", help="Expression").positional().required())
command.add_tip("Expressions starting with `-` are accepted.")
command.add_tip("Use quotes if you use spaces in expressions.")
A calculator

usage: calc <expr> [OPTIONS]

arguments:
  expr    Expression

options:
  -h, --help       Show this help message
  -V, --version    Show version

tip: Use '--' to pass values starting with '-' as positionals:  calc -- -10.18
tip: Expressions starting with `-` are accepted.
tip: Use quotes if you use spaces in expressions.

Smart default tip — when positional arguments are defined, ArgMojo automatically adds a built-in tip explaining the -- separator. The example in this default tip adapts based on whether negative numbers are auto-detected: if they are, it uses -my-value; otherwise, it uses -10.18.

User-defined tips appear below the built-in tip.


Multiple tips can be added; each is displayed on its own line prefixed with Tip:.

Version Display

Every command automatically supports --version (or -V).

myapp --version
myapp -V

Output:

myapp 1.0.0

The version string is set when creating the Command:

var command = Command("myapp", "Description", version="1.0.0")

After printing the version, the program exits cleanly with exit code 0.

CJK-Aware Help Alignment

ArgMojo automatically handles CJK (Chinese, Japanese, Korean) characters in help output. CJK ideographs and fullwidth characters occupy two terminal columns instead of one, so naïve byte- or codepoint-based padding would cause misaligned help columns.

ArgMojo’s help formatter uses display width (East Asian Width) to compute padding, so help descriptions stay aligned even when option names, positional names, subcommand names, or help text contain CJK characters.

See the Unicode East Asian Width specification for details on CJK character ranges and properties.

Example — mixed ASCII and CJK options:

var command = Command("工具", "一個命令行工具")
command.add_argument(
    Argument("output", help="Output path").long["output"]().short["o"]()
)
command.add_argument(
    Argument("編碼", help="設定編碼").long["編碼"]()
)
options:
  -o, --output <output>    Output path
      --編碼 <編碼>        設定編碼

Example — CJK subcommands:

var app = Command("工具", "一個命令行工具")
var init_cmd = Command("初始化", "建立新項目")
app.add_subcommand(init_cmd^)
var build_cmd = Command("構建", "編譯項目")
app.add_subcommand(build_cmd^)
commands:
  初始化    建立新項目
  構建      編譯項目

No configuration is needed — CJK-aware alignment is always active.

Full-Width → Half-Width Auto-Correction

CJK users frequently forget to switch input methods, accidentally typing fullwidth ASCII characters instead of their normal halfwidth equivalents:

  • --verbose instead of --verbose
  • = instead of =
  • -v instead of -v

ArgMojo automatically detects and corrects these characters before parsing, printing a coloured warning to stderr:

warning: detected full-width characters in '--verbose', auto-corrected to '--verbose'

What gets corrected:

  • Fullwidth ASCII characters (U+FF01–U+FF5E) are converted to their halfwidth equivalents (U+0021–U+007E) by subtracting 0xFEE0.
  • Fullwidth spaces (U+3000) are converted to regular spaces (U+0020). When a single token contains embedded fullwidth spaces (e.g., --name\u3000yuhao\u3000--verbose as one argv token), it is split into multiple arguments.
  • All tokens containing fullwidth ASCII are normalized (converted to halfwidth). Only tokens that start with - after correction are treated as options and trigger a warning. Positional values are also converted but no warning is emitted.

Example — fullwidth flag:

var app = Command("myapp", "My CLI")
app.add_argument(Argument("verbose", help="Verbose").long["verbose"]().short["v"]().flag())
var result = app.parse_arguments(["myapp", "--verbose"])
# result.get_flag("verbose") == True
# stderr: warning: detected full-width characters in '--verbose', auto-corrected to '--verbose'

Example — fullwidth equals syntax:

var app = Command("myapp", "My CLI")
app.add_argument(Argument("output", help="Output").long["output"]().takes_value())
var result = app.parse_arguments(["myapp", "--output=file.txt"])
# result.get_string("output") == "file.txt"

Disabling auto-correction:

Call disable_fullwidth_correction() if you prefer strict parsing:

var app = Command("myapp", "My CLI")
app.disable_fullwidth_correction()
# Now: fullwidth characters are NOT corrected

Whitespace handling:

By default, only fullwidth space (U+3000) triggers token splitting. Other Unicode whitespace characters (for example, EM SPACE U+2003) are treated as regular characters and do not cause tokens to be split.

This feature is enabled by default and works with both parse_arguments() and parse_known_arguments().