Help generation

Command

Command UDA provides few customizations that affect help text. It can be used for top-level command and subcommands.

Program name (i.e., the name of top-level command) and subcommand name can be provided to Command UDA as a parameter. If program name is not provided, then Runtime.args[0] (a.k.a. argv[0] from main function) is used. If subcommand name is not provided (e.g., @(Command.Description(...))), then the name of the type that represents the command is used.
Usage – allows custom usage text. By default, the parser calculates the usage message from the arguments it contains but this can be overridden with Usage call. If the custom text contains %(PROG) then it will be replaced by the command/program name.
Description – used to provide a description of what the command/program does and how it works. In help messages, the description is displayed between the usage string and the list of the command arguments.
ShortDescription – used to provide a brief description of what the subcommand does. It is applicable to subcommands only and is displayed in Available commands section on help screen of the parent command.
Epilog – custom text that is printed after the list of the arguments.

Usage, Description, ShortDescription and Epilog modifiers take either string or string function() value – the latter can be used to return a value that is not known at compile time.

A default subcommand is marked with (default) next to its name in Available commands section on help screen of the parent command.

Argument

There are some customizations supported on argument level for both PositionalArgument and NamedArgument UDAs:

Description – provides brief description of the argument. This text is printed next to the argument in the argument-list section of a help message. Description takes either string or string function() value – the latter can be used to return a value that is not known at compile time.
Hidden – can be used to indicate that the argument shouldn’t be printed in help message.
Placeholder – provides custom text that is used to indicate the value of the argument in help message.
PrintDefaultValueInHelp – overrides whether the default value of the argument is printed in help message.

Default value of an argument

The default value of an optional argument is printed next to its description if there is something meaningful to print: either the type of the argument is enum or the argument is initialized with a value that is different from the init value of its type. Required arguments never print their default value automatically since it is never used.

The value is printed in the same format that is expected in command line, so it can be copy-pasted from help screen: values of an array are printed as a comma-separated list and values of an associative array are printed as a comma-separated list of key=value pairs.

PrintDefaultValueInHelp modifier overrides this behavior: it takes either bool (true – always print the default value, false – never print it) or a function that returns Nullable!string (null – don’t print the default value, otherwise the returned string is printed as the default value) – the latter can be used to provide a value that is not known at compile time.

import argparse;
import std.typecons: Nullable;

struct T
{
    enum Mode { fast, slow }

    @(NamedArgument.Description("path to config file"))
    string config = "/etc/app.conf";

    @(NamedArgument.Description("mode to use"))
    Mode mode;

    @(NamedArgument.Description("tags to filter by"))
    string[] tags;

    // default value is provided in runtime
    @(NamedArgument.Description("number of threads")
     .PrintDefaultValueInHelp(() => Nullable!string("number of CPUs")))
    int threads;

    // default value is not printed even though it's not empty
    @(NamedArgument.Description("output file").PrintDefaultValueInHelp(false))
    string output = "out.txt";
}

T t;
CLI!T.parseArgs(t, ["-h"]);

This example prints the following:

Optional arguments:
  --config CONFIG       path to config file (default: /etc/app.conf)
  --mode {fast,slow}    mode to use (default: fast)
  --tags TAGS ...       tags to filter by
  --threads THREADS     number of threads (default: number of CPUs)
  --output OUTPUT       output file
  -h, --help            Show this help message and exit

Help text styling

argparse uses Config.styling to determine what style should be applied to different parts of the help text. Please refer to ANSI coloring and styling section for details.

Example

Here is an example of how this customization can be used:

import argparse;

@(Command("MYPROG")
.Description("custom description")
.Epilog("custom epilog")
)
struct T
{
    @NamedArgument  string s;
    @(NamedArgument.Placeholder("VALUE"))  string p;

    @(NamedArgument.Hidden)  string hidden;

    enum Fruit { apple, pear };
    @(NamedArgument("f","fruit").Required.Description("This is a help text for fruit. Very very very very very very very very very very very very very very very very very very very long text")) Fruit f;

    @(NamedArgument.AllowedValues(1,4,16,8)) int i;

    @(PositionalArgument(0).Description("This is a help text for param0. Very very very very very very very very very very very very very very very very very very very long text")) string param0;
    @(PositionalArgument(1).AllowedValues("q","a")) string param1;
}

T t;
CLI!T.parseArgs(t, ["-h"]);

This example will print the following help message:

Argument groups

By default, parser groups command line arguments into “required arguments” and “optional arguments” when displaying help message. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using ArgumentGroup UDA.

This UDA has some customization for displaying help text:

Description – provides brief description of the group. This text is printed right after group name. It takes either string or string function() value – the latter can be used to return a value that is not known at compile time.

Example:

import argparse;

@(Command("MYPROG")
.Description("custom description")
.Epilog("custom epilog")
)
struct T
{
    @(ArgumentGroup("group1").Description("group1 description"))
    {
        @NamedArgument
        {
            string a;
            string b;
        }
        @PositionalArgument string p;
    }

    @(ArgumentGroup("group2").Description("group2 description"))
    @NamedArgument
    {
        string c;
        string d;
    }
    @PositionalArgument string q;
}

T t;
CLI!T.parseArgs(t, ["-h"]);

When an argument is attributed with a group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages:

Last modified: 11 September 2026