picocli - a mighty tiny command line interface

@Parameters fields are applied to a command line argument if their index matches the argument’s position. The default index is *, meaning all positions. A @Parameters field with index = "*" is applied multiple times: once for each positional parameter on the command line.

When a @Parameters field is applied (because its index matches the index of the positional parameter), the field may consume zero, one or more arguments, depending on its arity.

When an option is defined with arity = "0..1", it may or not have a parameter value.

The fallback value determines what value is assigned when the option is specified without a value, while the default value determines what value is assigned when the option is not specified at all.

This feature is commonly used when an application wants to combine two options into one: the presence or absence of the option can be used like a boolean flag to trigger some behaviour, and the option value can be used to modify this behaviour.

An example use case is an option that switches on logging when present, with an optional value to set the log level. For example:

Another example use case is password options.

Be careful when defining commands that have both an option with an optional parameter and a positional parameter.

For example:

When -x VALUE is specified on the command line, this results in an error: Missing required parameter: <file>.

Users can use the end-of-options delimiter and disambiguate the input with -x ‐‐ VALUE, but this may not be obvious to many users. One idea is to show the end-of-options delimiter in the usage help. Another idea is to make use of the IParameterPreprocessor Parser Plugin introduced with picocli 4.6.

An alternative is to avoid the use of optional parameters and use the default arity in this scenario to eliminate the ambiguity altogether.

javaclass MandatoryOption {
    @Option(names = "-n", required = true, description = "mandatory number")
    int number;

    @Parameters
    File[] files;
}

// invalid: missing option -n
<command> file1 file2 file3

// valid: required option -n has a value
<command> -n 123 file1 file2 file3

javaclass BothOptionAndParametersMandatory {
    @Parameters(arity = "1..*", description = "at least one File")
    File[] files;

    @Option(names = "-n", required = true, description = "mandatory number")
    int number;
}

// invalid: missing file parameters
<command> -n 123

// valid: both required fields have a value
<command> -n 123 file1

java@Command(name = "exclusivedemo")
public class MutuallyExclusiveOptionsDemo {

    @ArgGroup(exclusive = true, multiplicity = "1")
    Exclusive exclusive;

    static class Exclusive {
        @Option(names = "-a", required = true) int a;
        @Option(names = "-b", required = true) int b;
        @Option(names = "-c", required = true) int c;
    }
}

Usage: exclusivedemo (-a=<a> | -b=<b> | -c=<c>)

javaMutuallyExclusiveOptionsDemo example = new MutuallyExclusiveOptionsDemo();
CommandLine cmd = new CommandLine(example);

try {
    cmd.parseArgs("-a=1", "-b=2");
} catch (MutuallyExclusiveArgsException ex) {
    assert "Error: -a=<a>, -b=<b> are mutually exclusive (specify only one)"
            .equals(ex.getMessage());
}

Annotate a field or method with @ArgGroup(exclusive = false) to create a group of dependent options and positional parameters that must co-occur. For example:

The above example defines a command with dependent options -a, -b and -c that must co-occur.

The group itself has a multiplicity attribute that defines how many times the group may be specified within the command. In this example the group uses the default multiplicity, multiplicity = "0..1", meaning that the group may be omitted or specified once.

The synopsis of this command is:

When the first option in the group is matched, picocli creates an instance of the Dependent class and assigns it to the @ArgGroup-annotated dependent field.

Note that the options are defined as required = true; this means required within the group, not required within the command.

Picocli will validate the arguments and throw a MissingParameterException if not all dependent arguments were specified. For example:

In mutually dependent groups it is possible to have one or more options that are not required. This is different from exclusive groups, where all options are always required.

It is useful to be able to define a co-occurring group as (-a -b [-c]) so that both -a -b -c and -a -b are valid on the command line, but not -a -c for example. This can be implemented by marking the optional option with required = false, as in the below example:

More than one option can be optional in mutually dependent groups, but it is recommended to have at least one required option in the group (or there is not much point in using a mutually dependent group).

The example below uses groups to define options sections in the usage help. When a group has a non-null heading (or headingKey), the options in the group are given the specified heading in the usage help message. The headingKey attribute can be used to get the heading text from the command’s resource bundle.

This works for mutually exclusive or co-occurring groups, but it is also possible to define a group that does no validation but only creates an option section in the usage help.

Annotate a field or method with @ArgGroup(validate = false) to create a group for display purposes only. For example:

This prints the following usage help message:

Note that the heading text must end with %n to insert a newline between the heading text and the first option. This is for consistency with other headings in the usage help, like @Command(headerHeading = "Usage:%n", optionListHeading = "%nOptions:%n").

Options that are not in any argument group are always displayed before any group option sections.

The ordering of group option sections can be controlled with the order attribute. For example:

Note that setting validate = false means that picocli won’t validate user input for the group. For example, even for groups with multiplicity = 1, when the end user specifies the group multiple times, no error is shown. If the group is a single-value field, only the last occurrence is stored and previous occurrences are silently dropped.

If validation is needed, the recommendation is to make the field holding the group a collection, and doing Custom Validation. For example to ensure that this collection holds only a single element:

java@Command(name = "repeating-composite-demo")
public class CompositeGroupDemo {

    @ArgGroup(exclusive = false, multiplicity = "1..*")
    List<Composite> composites;

    static class Composite {
        @ArgGroup(exclusive = false, multiplicity = "0..1")
        Dependent dependent;

        @ArgGroup(exclusive = true, multiplicity = "1")
        Exclusive exclusive;
    }

    static class Dependent {
        @Option(names = "-a", required = true) int a;
        @Option(names = "-b", required = true) int b;
        @Option(names = "-c", required = true) int c;
    }

    static class Exclusive {
        @Option(names = "-x", required = true) boolean x;
        @Option(names = "-y", required = true) boolean y;
        @Option(names = "-z", required = true) boolean z;
    }
}

Usage: repeating-composite-demo ([-a=<a> -b=<b> -c=<c>] (-x | -y | -z))...

javaCompositeGroupDemo example = new CompositeGroupDemo();
CommandLine cmd = new CommandLine(example);

cmd.parseArgs("-x", "-a=1", "-b=1", "-c=1", "-a=2", "-b=2", "-c=2", "-y");
assert example.composites.size() == 2;

Composite c1 = example.composites.get(0);
assert c1.exclusive.x;
assert c1.dependent.a == 1;
assert c1.dependent.b == 1;
assert c1.dependent.c == 1;

Composite c2 = example.composites.get(1);
assert c2.exclusive.y;
assert c2.dependent.a == 2;
assert c2.dependent.b == 2;
assert c2.dependent.c == 2;

Options used in argument groups should define default values via the @Option(defaultValue = "…​") annotation.

When default values are defined in the annotation, the ${DEFAULT-VALUE} variable can be used to show the default value in the description of options in an argument group. For example:

When the default value is defined in the annotation, the usage help shows the correct default value:

Applications need to do extra work for argument group options with default values. Picocli does not instantiate the group if none of the options in the group is specified on the command line, so applications need to do this manually.

Below are some recommendations for using default values in argument group options and positional parameters:

• specify default values in both the @Option annotation, and in the initial value of the @Option-annotated field. Yes, that means some duplication. This recommendation also holds for positional @Parameters.

• the application needs to manually instantiate the @ArgGroup-annotated field. More details follow below.

The default value in the @Option or @Parameters annotation means that picocli can show the default value in the usage help, and the initial value means that any new instance of the group that contains the option will already have the default value assigned to that option field.

The example below shows an option that defines the default value in the annotation as well as in the initial value of the field:

Next, the application needs to manually instantiate the @ArgGroup-annotated field. There is a trade-off:

• instantiating the @ArgGroup-annotated field in the declaration is simple and short but applications cannot easily detect whether a group option was specified on the command line or not

• leaving the @ArgGroup-annotated field null in the declaration allows applications to easily detect whether a group option was specified on the command line, but is a bit more code

The example below shows the first idea: instantiating the group object in the declaration. This way, the group object is never null and (if you followed the previous recommendation) all option fields in this group object will have the default value as their initial value.

Alternatively, applications can initialize the group objects in the business logic: in the run or call method. This allows the application to determine whether the user specified a value for any of the options in the group.

The example below demonstrates initializing the group objects in the business logic:

java@Command(name = "grades", mixinStandardHelpOptions = true, version = "grades 1.0")
public class Grades implements Runnable {

    static class StudentGrade {
        @Parameters(index = "0") String name;
        @Parameters(index = "1") BigDecimal grade;
    }

    @ArgGroup(exclusive = false, multiplicity = "1..*")
    List<StudentGrade> gradeList;

    @Override
    public void run() {
        gradeList.forEach(e -> System.out.println(e.name + ": " + e.grade));
    }

    public static void main(String[] args) {
        System.exit(new CommandLine(new Grades()).execute(args));
    }
}

Alice 3.1 Betty 4.0 "X Æ A-12" 3.5 Zaphod 3.4

Alice: 3.1
Betty: 4.0
X Æ A-12: 3.5
Zaphod: 3.4

javapublic static void main(String... args) {
  int exitCode = new CommandLine(new MyApp()).execute(args);
  System.exit(exitCode);
}

java@Command(name = "greet")
class Greet implements Callable<Integer> {
    public Integer call() {
        System.out.println("hi");
        return 1;
    }

    // define a "shout" subcommand with a @Command-annotated method
    @Command
    int shout() {
        System.out.println("HI!");
        return 2;
    }
}

assert 1 == new CommandLine(new Greet()).execute();
assert 2 == new CommandLine(new Greet()).execute("shout");

java@Command(name = "wave")
class Gesture implements Runnable, IExitCodeGenerator {

    @Override public void run() {
        System.out.println("wave");
    }

    @Override public int getExitCode() {
        return 3;
    }
}

assert 3 == new CommandLine(new Gesture()).execute();

java@Command(exitCodeOnInvalidInput = 123,
   exitCodeOnExecutionException = 456)

javaclass MyMapper implements IExitCodeExceptionMapper {
    @Override
    public int getExitCode(Throwable t) {
        if (t instanceof FileNotFoundException) {
            return 74;
        }
        return 1;
    }
}

Before:

After:

Before:

After:

Before:

After:

The IParseResultHandler2 interface has been deprecated in picocli 4.0 in favor of IExecutionStrategy. The existing built-in handlers RunLast, RunAll and RunFirst implement the IExecutionStrategy interface and can still be used:

• the RunLast handler prints help if requested, and otherwise gets the last specified command or subcommand and tries to execute it as a Runnable, Callable or Method. This is the default execution strategy.

• the RunFirst handler prints help if requested, and otherwise executes the top-level command as a Runnable, Callable or Method

• the RunAll handler prints help if requested, and otherwise executes all commands and subcommands that the user specified on the command line as Runnable, Callable or Method tasks

Before

After

The ParseResult can be used to get the return value from a Callable or Method subcommand:

javaCallable<Object> callable = new MyCallable();
CommandLine cmd = new CommandLine(callable);
try {
    ParseResult parseResult = cmd.parseArgs(args);

    // Did user request usage help (--help)?
    if (cmd.isUsageHelpRequested()) {
        cmd.usage(cmd.getOut());
        return cmd.getCommandSpec().exitCodeOnUsageHelp();

    // Did user request version help (--version)?
    } else if (cmd.isVersionHelpRequested()) {
        cmd.printVersionHelp(cmd.getOut());
        return cmd.getCommandSpec().exitCodeOnVersionHelp();
    }
    // invoke the business logic
    Object result = callable.call();
    cmd.setExecutionResult(result);
    return cmd.getCommandSpec().exitCodeOnSuccess();

// invalid user input: print error message and usage help
} catch (ParameterException ex) {
    cmd.getErr().println(ex.getMessage());
    if (!UnmatchedArgumentException.printSuggestions(ex, cmd.getErr())) {
        ex.getCommandLine().usage(cmd.getErr());
    }
    return cmd.getCommandSpec().exitCodeOnInvalidInput();

// exception occurred in business logic
} catch (Exception ex) {
    ex.printStackTrace(cmd.getErr());
    return cmd.getCommandSpec().exitCodeOnExecutionException();
}

When the user specified invalid input, the parser throws a ParameterException. In the execute method, such exceptions are caught and passed to the IParameterExceptionHandler.

The default parameter exception handler prints an error message describing the problem, followed by either suggested alternativeshttps://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.UnmatchedArgumentException.html#printSuggestions(picocli.CommandLine.ParameterException,java.io.PrintWriter) for mistyped options, or the full usage help message of the problematic command. Finally, the handler returns an exit code. This is sufficient for most applications.

Sometimes you want to display a shorter message. For example, the grep utility does not show the full usage help when it gets an invalid argument:

You can customize how your application handles invalid user input by setting a custom IParameterExceptionHandler:

Where the IParameterExceptionHandler implementation could be something like this:

When the business logic throws an exception, this exception is caught and passed to the IExecutionExceptionHandler.

The default execution exception handling results in the stack trace of the exception being printed and an exit code being returned. This is sufficient for most applications.

If you have designed your business logic to throw exceptions with user-facing error messages, you want to print this error message instead of the stack trace. This can be accomplished by installing a custom IExecutionExceptionHandler, like this:

Where the IExecutionExceptionHandler implementation could look something like this:

The parseArgs method is useful in test code that only exercises the parsing logic, without involving the business logic. For example:

The execute method never throws an exception, and for some applications this is undesirable.

The parseArgs method can also be useful when the main method of your application is called by another application, and this other application is responsible for error handling.

An common use case is when your application is called as part of the build. For example, Maven provides the exec-maven-pluginhttps://www.mojohaus.org/exec-maven-plugin/ with exec:java goalhttps://www.mojohaus.org/exec-maven-plugin/java-mojo.html, and Gradle similarly provides the Exechttps://docs.gradle.org/current/dsl/org.gradle.api.tasks.Exec.html and JavaExechttps://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html tasks.

The Maven exec:java goal invokes the target class in the same Maven process. In this case, we don’t want to call System.exit, because it would stop the entire Maven process, and additionally, we want the exceptions thrown by the command line application to be handled by Maven.

One idea is to provide a separate main method that uses parseArgs instead of execute. For example:

Then, in the build configuration, invoke nested class MyApp.NoSystemExit instead of MyApp to let the build tool handle any exceptions and avoid calling System.exit.

An alternative to the above solution is to decide at runtime whether to call System.exit or not.

The example implementation below demonstrates how to use system properties to determine whether to call System.exit or not:

Picocli’s own Bash and ZSH completion script generator tool uses this method: when this tool is called with a specific system property (picocli.autocomplete.systemExitOnError) it will call System.exit when an error occurs.

Methods annotated with @Option and @Parameters can do simple input validation by throwing a ParameterException when invalid values are specified on the command line.

The following example validates that the value specified for the --prime option is a prime number:

Another common scenario is that the combination of multiple options and positional parameters is valid. One way to accomplish this is to perform such validation at the beginning of the business logic.

The following example validates that at least one of the --xml, --csv, or --json options is specified:

If you want to keep your validation declarative and annotation-based, take a look at JSR 380https://jcp.org/en/jsr/detail?id=380.

JSR-380 is a specification of the Java API for bean validation, part of JavaEE and JavaSE, which ensures that the properties of a bean meet specific criteria, using annotations such as @NotNull, @Min, and @Max.

The picocli wiki has a full examplehttps://github.com/remkop/picocli/wiki/JSR-380-BeanValidation, below is a snippet:

The above JSR-380 BeanValidation can also be accomplished with a custom IExecutionStrategy that does the validation before executing the command. This moves the validation logic into a separate class. Picocli invokes this logic, removing the need to call a validate method from the business logic.

Such a custom execution strategy could look like this:

The application can wire in this custom execution strategy as follows:

When abbreviations are enabled, users can specify the initial letter(s) of the first component and optionally of one or more subsequent components of an option or subcommand name.

"Components" are separated by - dash characters or by case, so for example, both --CamelCase and --kebab-case have two components.

When the user specifies input that can match multiple options or subcommands, the parser throws a ParameterException. When applications use the execute method, an error message and the usage help is displayed to the user.

For example, given a command with subcommands help and hello, then ambiguous user input like hel will show this error message:

When an argument can match both an abbreviated long option and a set of clustered short options, picocli matches the long option. This is the case regardless of abbreviations, but be aware that with abbreviated options enabled, the chance of such collisions increases.

For example:

When abbreviated options are enabled, user input -AB will match the long -AaaBbb option, but not the -A and -B options.

java@Option(names = "-p") int port;

<command> -p 80 -p 8080

javaclass OnlyThree {
    @Parameters(arity = "3") String[] values;
}

java OnlyThree 1 2 3 4 5

A special case of unmatched input are arguments that resemble options but don’t match any of the defined options. Picocli determines if a value "resembles an option" by comparing its leading characters to the prefix characters of the known options.

For example, the value -z is considered an unknown option when we have a command that only defines options -x and -y:

The above defines options -x and -y, but no option -z. So what should the parser do when the user gives input like this?

One possibility is to silently accept such values as positional parameters, but this is often not desirable.

By default, when the value resembles an option, picocli throws an UnmatchedArgumentException rather than treating it as a positional parameter.

Picocli 3.0 introduced the CommandLine::setUnmatchedOptionsArePositionalParams method that can be used to force the parser to treat arguments resembling an option as positional parameters. For example:

When unmatchedOptionsArePositionalParams is set to true, the unknown option -z is treated as a positional parameter. The next argument -x is recognized and processed as a known option like you would expect.

By default, options accept parameter values that "resemble" (but don’t exactly match) an option.

Picocli 4.4 introduced a CommandLine::setUnmatchedOptionsAllowedAsOptionParameters method that makes it possible to configure the parser to reject values that resemble options as option parameters. Setting this to false will result in values resembling option names being rejected as option values.

For example:

By default, a value like -z, which resembles an option, is accepted as the parameter for -x:

After setting the unmatchedOptionsAllowedAsOptionParameters parser option to false, values resembling an option are rejected as parameter for -x:

This will throw an UnmatchedArgumentException with message:

Since picocli 4.4, the parser will no longer assign values that match a subcommand name or an option name to options that take a parameter, unless the value is in quotes. For example:

In previous versions of picocli, the above command would accept input -x -y, and the value -y would be assigned to the x String field. As of picocli 4.4, the above input will be rejected with an error message indicating that the -x option requires a parameter.

If it is necessary to accept values that match option names, such values need to be quoted. For example:

This will print the following output:

Picocli 4.7.0 introduces two parser configuration options to change this behaviour:

• CommandLine::setAllowOptionsAsOptionParameters allows options to consume option names

• CommandLine::setAllowSubcommandsAsOptionParameters allows options to consume subcommand names

When set to true, all options in the command (options that take a parameter) can consume values that match option names or subcommand names.

This means that any option will consume the maximum number of arguments possible for its arity.

The parser configuration options in the previous section apply to all options in the command.

Some applications may want to enable options consuming option names or subcommands for some options, but not for all options in the command. Such applications can replace or augment picocli’s parser by doing custom parameter processing for such options. For example:

The above code assigns whatever command line argument that follows the -x option to that option, and allows input like the following:

From picocli 3.7, quotes around command line parameters are preserved by default (previously they were removed). This can be configured with CommandLine::setTrimQuotes, or the parser configuration trimQuotes. From picocli 4.0, quoted arguments can contain nested quoted substrings, to give end users fine-grained control over how values are split.

If CommandLine::setTrimQuotes, or the parser configuration trimQuotes is set to true, picocli will remove quotes from the command line arguments, as follows:

• As each command line argument is processed, the below smart unquote procedure is used to trim the outermost quotes.

• Next, if the option or positional parameter has a split regex defined, the parameter value is split while respecting quotes: the split regex is not matched if it occurs in a quoted substring of the parameter value. Each of the parts found by the splitting process will have its quotes removed using the below "smart unquote" procedure.

See the Splitting Quoted Parameters section below for examples.

§Smart Unquote

By default, if the option or positional parameter has a split regex defined, parameter values are split into parts while respecting quotes: the split regular expression is not matched inside a quoted region.

Example:

Given input like below:

This results in the parts array having the following values, assuming the parser configuration trimQuotes is false (the default):

If the parser configuration trimQuotes is true, the above example would be split into the following values (with quotes trimmed from the resulting parts):

Given input like below:

This results in the parts array having the following values:

Or, if the parser configuration trimQuotes is true:

To preserve quotes when trimQuotes is true, specify additional nested quotes on the command line. For example:

With parser configuration trimQuotes set to true, the above input gives the following values:

This "smart splitting" (respecting quotes) can be switched off with CommandLine::setSplitQuotedStrings: setting the splitQuotedStrings parser attribute to true switches off smart splitting, and the split regex is applied to the parameter value regardless of quotes.

javainterface INegatableOptionTransformer {
    /**
     * Returns the negative form of the specified option name for the parser to recognize
     * when parsing command line arguments.
     * @param optionName the option name to create a negative form for,
     *                   for example {@code --force}
     * @param cmd the command that the option is part of
     * @return the negative form of the specified option name, for example {@code --no-force}
     */
    String makeNegative(String optionName, CommandSpec cmd);

    /**
     * Returns the documentation string to show in the synopsis and usage help message for
     * the specified option. The returned value should be concise and clearly suggest that
     * both the positive and the negative form are valid option names.
     * @param optionName the option name to create a documentation string for,
     *                   for example {@code --force}, or {@code -XX:+<option>}
     * @param cmd the command that the option is part of
     * @return the documentation string for the negatable option,
     *         for example {@code --[no-]force}, or {@code -XX:(+|-)<option>}
     */
    String makeSynopsis(String optionName, CommandSpec cmd);
}

Options or positional parameters can be assigned an IParameterConsumer that implements custom logic to process the parameters for this option or this position. When an option or positional parameter with a custom IParameterConsumer is matched on the command line, picocli’s internal parser is temporarily suspended, and the custom parameter consumer becomes responsible for consuming and processing as many command line arguments as needed.

This can be useful when passing options through to another command.

For example, the unix findhttps://en.wikipedia.org/wiki/Find_(Unix) command has a -exechttps://en.wikipedia.org/wiki/Find_(Unix)#Execute_an_action option to execute some action for each file found. Any arguments following the -exec option until a ; or + argument are not options for the find command itself, but are interpreted as a separate command and its options.

The example below demonstrates how to implement find -exec using this API:

Introduced in picocli 4.6, the IParameterPreprocessor is also a parser plugin, similar to IParameterConsumer, but more flexible.

Options, positional parameters and commands can be assigned an IParameterPreprocessor that implements custom logic to preprocess the parameters for this option, position or command. When an option, positional parameter or command with a custom IParameterPreprocessor is matched on the command line, picocli’s internal parser is temporarily suspended, and this custom logic is invoked.

This custom logic may completely replace picocli’s internal parsing for this option, positional parameter or command, or augment it by doing some preprocessing before picocli’s internal parsing is resumed for this option, positional parameter or command.

The "preprocessing" actions can include modifying the stack of command line parameters, or modifying the model.

§Example use case

edit [--open[=<editor>]] <file>

java@Command(name = "edit")
class Edit {

    @Parameters(index = "0", arity="0..1", description = "The file to edit.")
    File file;

    enum Editor { defaultEditor, eclipse, idea, netbeans }

    @Option(names = "--open", arity = "0..1", preprocessor = Edit.MyPreprocessor.class,
        description = {
           "Optionally specify the editor to use (${COMPLETION-CANDIDATES}). " +
           "If omitted the default editor is used. ",
           "Example: edit --open=idea FILE opens IntelliJ IDEA (notice the '=' separator)",
           "         edit --open FILE opens the specified file in the default editor"
        })
    Editor editor = Editor.defaultEditor;

    static class MyPreprocessor implements IParameterPreprocessor {
        public boolean preprocess(Stack<String> args,
                                  CommandSpec commandSpec,
                                  ArgSpec argSpec,
                                  Map<String, Object> info) {
            // we need to decide whether the next arg is the file to edit
            // or the name of the editor to use...
            if (" ".equals(info.get("separator"))) { // parameter was not attached to option

                // act as if the user specified --open=defaultEditor
                args.push(Editor.defaultEditor.name());
            }
            return false; // picocli's internal parsing is resumed for this option
        }
    }
}

# User input # Command State
# --------------------------
--open A B   # editor: defaultEditor, file: A,    unmatched: [B]
--open A     # editor: defaultEditor, file: A,    unmatched: []
--open=A B   # editor: A,             file: B,    unmatched: []
--open=A     # editor: A,             file: null, unmatched: []

java@Option(names = {"-V", "--version"}, versionHelp = true, description = "display version info")
boolean versionInfoRequested;

@Option(names = {"-h", "--help"}, usageHelp = true, description = "display this help message")
boolean usageHelpRequested;

javaApp app = CommandLine.populateCommand(new App(), args);
if (app.usageHelpRequested) {
    CommandLine.usage(new App(), System.out);
    return;
}

javaCommandLine commandLine = new CommandLine(new App());
commandLine.parseArgs(args);
if (commandLine.isUsageHelpRequested()) {
    commandLine.usage(System.out);
    return;
} else if (commandLine.isVersionHelpRequested()) {
    commandLine.printVersionHelp(System.out);
    return;
}
// ... run App's business logic

java@Command(mixinStandardHelpOptions = true, version = "auto help demo - picocli 3.0")
class AutoHelpDemo implements Runnable {

    @Option(names = "--option", description = "Some option.")
    String option;

    @Override public void run() { /* ... */ }
}

Usage: <main class> [-hV] [--option=<option>]
      --option=<option>   Some option.
  -h, --help              Show this help message and exit.
  -V, --version           Print version information and exit.

javaimport picocli.CommandLine.HelpCommand;

@Command(name = "myapp", subcommands = {HelpCommand.class, Subcommand.class})
class MyCommand implements Runnable {
    // ...
}

bashmyapp help subcommand

bashmyapp help

java@Command(helpCommand = true)

javapublic interface IHelpCommandInitializable2 {
    /**
     * Initializes this object with the information needed to implement a help command that
     * provides usage help for other commands.
     *
     * @param helpCommandLine the {@code CommandLine} object associated with this help command.
      *                       Implementors can use this to walk the command hierarchy and
      *                       get access to the help command's parent and sibling commands.
     * @param colorScheme the color scheme to use when printing help, including whether
     *                    to use Ansi colors or not
     * @param outWriter the output writer to print the usage help message to
     * @param errWriter the error writer to print any diagnostic messages to,
     *                  in addition to the output from the exception handler
     */
    void init(CommandLine helpCommandLine,
              Help.ColorScheme colorScheme,
              PrintWriter outWriter,
              PrintWriter errWriter);
}

As of picocli 0.9.8, applications can specify version information in the version attribute of the @Command annotation.

The CommandLine.printVersionHelp(PrintStream) method extracts the version information from this annotation and prints it to the specified PrintStream.

The version may specify multiple Strings. Each will be printed on a separate line.

The CommandLine.printVersionHelp(PrintStream) method will print the above as:

As of picocli 4.0, the version strings may contain system properties and environment variables. For example:

Depending on your environment, that may print something like:

The version strings may contain markup to show ANSI styles and colors. For example:

The markup will be rendered as ANSI escape codes on supported systems.

Pre-defined Styles Pre-defined Colors

bold

black

faint

red

underline

green

italic

yellow

blink

blue

reverse

magenta

reset

cyan

white

java@Command(name = "commit",
        sortOptions = false,
        headerHeading = "@|bold,underline Usage|@:%n%n",
        synopsisHeading = "%n",
        descriptionHeading = "%n@|bold,underline Description|@:%n%n",
        parameterListHeading = "%n@|bold,underline Parameters|@:%n",
        optionListHeading = "%n@|bold,underline Options|@:%n",
        header = "Record changes to the repository.",
        description = "Stores the current contents of the index in a new commit " +
                "along with a log message from the user describing the changes.")
class GitCommit { /* ... */ }

§15.3. Styles and Colors in Application Output

javaimport picocli.CommandLine.Help.Ansi;
// ...
String str = Ansi.AUTO.string("@|bold,green,underline Hello, colored world!|@");
System.out.println(str);

§15.4. More Colors

0x00-0x07:  standard colors (the named colors)
0x08-0x0F:  high intensity colors (often similar to named colors + bold style)
0x10-0xE7:  6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
0xE8-0xFF:  grayscale from black to white in 24 steps

${key:-defaultValue}
${sys:key:-defaultValue}
${env:key:-defaultValue}
${bundle:key:-defaultValue}

${bundle:a:-${env:b:-${sys:c:-X}}}