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:
| Syntax | Value |
|---|---|
| (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)
| Syntax | Result |
|---|---|
--output=file.txt | "file.txt" (OK) |
--output file.txt | error |
--output | error |
-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.
| Element | Default style | ANSI code |
|---|---|---|
| Section headers | bold + underline + bright yellow | \x1b[1;4m\x1b[93m |
| Program name | bold magenta | \x1b[1;35m |
| Short option names | bold green | \x1b[1;32m |
| Long option names | bold cyan | \x1b[1;36m |
| Value names / metavar | bold yellow | \x1b[1;33m |
| Positional arg names | bold green | \x1b[1;32m |
| Subcommand names | bold cyan | \x1b[1;36m |
| Deprecation warnings | orange (dark yellow) | \x1b[33m |
| Parse errors | bright red | \x1b[91m |
| Description text | default 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):
| Name | ANSI code | Preview |
|---|---|---|
RED | 91 | bright red |
GREEN | 92 | bright green |
YELLOW | 93 | bright yellow |
BLUE | 94 | bright blue |
MAGENTA | 95 | bright magenta |
PINK | 95 | alias for MAGENTA |
CYAN | 96 | bright cyan |
WHITE | 97 | bright white |
ORANGE | 33 | orange/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 method | Effect 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:
--verboseinstead of--verbose=instead of=-vinstead 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 subtracting0xFEE0. - Fullwidth spaces (
U+3000) are converted to regular spaces (U+0020). When a single token contains embedded fullwidth spaces (e.g.,--name\u3000yuhao\u3000--verboseas 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().