Quick Guide

Let’s break it down into small steps:

This is the basic skeleton of almost any picocli application.

Like any professional command line application, ASCIIArt has --help and --version options. The --help option shows the user how to use the application. Picocli generates this usage help message automatically:

Execute the ASCIIArt example by clicking the blue Execute button below.

Let’s break it down into small steps:

This is the basic skeleton of an picocli application with subcommands.

In addition to the two user defined subcommands, the ISOCodeResolver app offers a help subcommand, which prints the usage help message to the console. Picocli generates this usage help message automatically:

Execute the ISOCodeResolver example by clicking the blue Execute button below.

An option must have one or more names. Option names commonly start with - or --, but picocli lets you use any option name you want.

The below example shows options with one or more names, options that take an option parameter, and a help option.

Picocli matches the option names to set the field values.

Picocli supports POSIX clustered short options: one or more single-character options without option-arguments, followed by at most one option with an option-argument, can be grouped behind one ‘-’ dash.

For example, for the Tar example above, the following command line invocations are equivalent:

For options and positional parameters marked as interactive, the user is prompted to enter a value on the console. When running on Java 6 or higher, picocli will use the Console.readPassword API so that user input is not echoed to the console.

The user manual has an example.

Any command line arguments that are not subcommands, options or option parameters are interpreted as positional parameters.

Use the (zero-based) index attribute to specify exactly which parameters to capture. Omitting the index attribute means the field captures all positional parameters. Array or collection fields can capture multiple values.

The index attribute accepts range values, so an annotation like @Parameters(index = "2..4") captures the arguments at index 2, 3 and 4. Range values can be open-ended. For example, @Parameters(index = "3..*") captures all arguments from index 3 and up.

For example:

Picocli initializes fields with the values at the specified index in the arguments array.

The user manual has more details about options and positional parameters, as well as the -- end-of-options delimiter and parameter files (@-files).

Out of the box, picocli can convert command line argument strings to a number of common data types.

See the user manual for the full list of built-in types, but in general all primitive types and their Object equivalent, any enum, and common classes like File, Date, URL, BigDecimal, regex Pattern etc. can be used as is. Applications running on Java 7 can use Path, and on Java 8 the new java.time classes can be used.

You can also use a custom type converter to handle data types other than the above built-in ones.

If an option or positional parameter can have multiple values, the field type must be an array, a Collection or a Map. Any Collection subclass like List, Set, or Queue can be used.

A common requirement is to have options with key-value pairs similar to Java’s system properties, like -Dkey=value. To achieve this, all you need to do is use a Map field.

Map fields may have any type for their key and value as long as a type converter is registered for both the key and the value type. Key and value types are inferred from the map’s generic type parameters. For example:

The following command line would result in four key-value entries in the map:

Options can be marked required to make it mandatory for the user to specify them on the command line. When a required option is not specified, a MissingParameterException is thrown from the parse method. For example:

Use the arity attribute to make @Parameters mandatory:

The simplest way to create a multi-valued option is to declare an annotated field whose type is an array, collection or a map.

Users may specify the same option multiple times. For example:

Each value is appended to the array or collection.

Options and parameters may also specify a split regular expression used to split each option parameter into smaller substrings. Each of these substrings is converted to the type of the collection or array. See Collections and Maps.

A single command line argument like the following will be split up and three int values are added to the array:

Sometimes you want to define an option that requires more than one option parameter for each option occurrence on the command line.

The arity attribute lets you control exactly how many parameters to consume for each option occurrence.

The arity attribute can specify an exact number of required parameters, or a range with a minimum and a maximum number of parameters. The maximum can be an exact upper bound, or it can be "*" to denote any number of parameters. For example:

A MissingParameterException is thrown when fewer than the miminum number of parameters is specified on the command line.

When the mixinStandardHelpOptions command attribute is set to true, picocli adds a mixin to the command that adds usageHelp and versionHelp options to the command. For example:

The usage help message for the above example looks like this:

Applications can define custom help options by setting attribute versionHelp = true, usageHelp = true or help = true. If one of the arguments specified on the command line is a "help" option, picocli will not throw a MissingParameterException when required options are missing.

For example:

Use these attributes for options that request the usage help message or version information to be shown on the console.

The CommandLine class offers two methods that allow external components to detect whether usage help or version information was requested (without inspecting the annotated domain object):

See also the chapter Printing Help Automatically of the user manual.

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, and may contain markup to show ANSI styles and colors. For example:

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

The @Command annotation supports a versionProvider attribute. Applications may specify a IVersionProvider implementation in this attribute, and picocli will instantiate this class and invoke it to collect version information.

The GitHub project has an example implementation that gets the version from the manifest file and another example that gets version information from a build-generated version properties file.

Picocli makes it easy for your application to generate a usage help message like this:

The usage help message is generated from annotation attributes, like below:

The various elements of the usage help message are easily customized with annotations.

Below shows the same usage help message as shown in the Expanded Example in the user manual, with ANSI escape codes enabled.

You can use colors and styles in the descriptions, header and footer of the usage help message.

Picocli supports a custom markup notation for mixing colors and styles in text, following a convention introduced by Jansi, where @| starts a styled section, and |@ ends it. Immediately following the @| is a comma-separated list of colors and styles, so @|STYLE1[,STYLE2]…​ text|@. For example:

Colors are applied as foreground colors by default. You can set background colors by specifying bg(<color>). For example, @|bg(red) text with red background|@. Similarly, fg(<color>) explicitly sets the foreground color.

The example below shows how this markup can be used to add colors and styles to the headings and descriptions of a usage help message:

Picocli will only emit ANSI escape codes on supported platforms. This includes most Unix and Linux platforms. See the Windows section of the user manual for the various options available to add coloring support to the Windows command console.

You can force picocli to either always use ANSI codes or never use ANSI codes regardless of the platform:

Subcommands can be registered programmatically or declaratively

For this example, we assume we created an alias git that invokes our Java application. This could also be a script or a function that calls our Java program:

Next, we call our command with some arguments like this:

Where git (actually java picocli.Demo$Git) is the top-level command, followed by a global option and a subcommand status with its own options.

Setting up the parser and parsing the command line could look like this:

The CommandLine.parse method returns a List with the recognized commands. The top-level command (the Java class invoked by git in this example) is always the first element in the returned list.

The returned List also contains all matched subcommands. Your application needs to inspect this list to see what subcommand was invoked and take appropriate action. For example:

As of Picocli 4.0, you may use the execute method to reduce error handling and other boilerplate code in your application.

In command line applications with subcommands, options of the top level command are often intended as "global" options that apply to all the subcommands. The @ParentCommand annotation makes it easy for subcommands to access their parent command options: subcommand fields annotated with @ParentCommand are initialized with a reference to the parent command. The user manual has an example showing how to use the @ParentCommand annotation.

After registering subcommands, calling the commandLine.usage method will show a usage help message that includes all subcommands in the order they were registered. For example:

The description for the subcommand in the list is taken from the subcommand’s first header line, or, if the subcommand does not have a header annotation, from the description.

Many command line applications return an exit code to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application.

The CommandLine.execute method introduced in picocli 4.0 returns an int, and applications can use this return value to call System.exit if desired. For example:

@Command-annotated classes that implement Callable and @Command-annotated methods can simply return an int or Integer, and this value will be returned from CommandLine.execute. For example:

Commands with a user object that implements Runnable can implement the IExitCodeGenerator interface to generate an exit code.

By default, the execute method returns CommandLine.ExitCode.OK (0) on success, CommandLine.ExitCode.SOFTWARE (1) when an exception occurred in the Runnable, Callable or command method, and CommandLine.ExitCode.USAGE (2) for invalid input. (These are common values according to this StackOverflow answer). This can be customized with the @Command annotation. For example:

Additionally, applications can configure a IExitCodeExceptionMapper to map a specific exception to an exit code.

While the execute method allows to run the CLI app in one single line of code, the various steps of the command execution are highly configurable. The following methods can be used to configure the behaviour of the execute method, you may make use of them to adapt the command execution to your needs:

Internally, the execute method parses the specified user input and populates the options and positional parameters defined by the annotations. When the user specified invalid input, this is handled by the IParameterExceptionHandler.

After parsing the user input, the business logic of the command is invoked: the run, call or @Command-annotated method. When an exception is thrown by the business logic, this is handled by the IExecutionExceptionHandler.

In most cases, the default handlers are sufficient. Customization of the default handlers in explained in depth in the handling errors section of the user manual.

Older versions of picocli supported run, call, invoke and parseWithHandlers convenience methods that were similar to execute but had limited support for parser configuration and and limited support for exit codes. These methods are deprecated as of picocli 4.0.

The migration section of the user manual assists you in migrating existing code to the newly introduced execute API.