picocli - a mighty tiny command line interface

Annotation-based Java command line parser, featuring usage help with ANSI colors, autocomplete and nested subcommands. In a single file, so you can include it in source form. This lets users run picocli-based applications without requiring picocli as an external dependency.

Now in BETA: command line autocompletion
Autocomplete is work in progress. Comments, bug reports, pull requests welcome!

How it works: annotate your class and picocli initializes it from the command line arguments, converting the input to strongly typed data. Supports git-like subcommands (and nested sub-subcommands), any option prefix style, POSIX-style grouped short options, custom type converters and more. Parser tracing facilitates troubleshooting.

Distinguishes between named options and positional parameters and allows both to be strongly typed. Multi-valued fields can specify an exact number of parameters or a range (e.g., 0..*, 1..2). Supports Map options like -Dkey1=val1 -Dkey2=val2, where both key and value can be strongly typed.

Generates polished and easily tailored usage help and version help, using ANSI colors where possible. Works with Java 5 or higher (but is designed to facilitate the use of Java 8 lambdas).

Releases - latest: 1.0.1
User manual: http://picocli.info
Command line autocompletion
API Javadoc
FAQ
Announcing picocli 1.0
Check out Thibaud Lepretre's picocli Spring boot starter!

Example

Annotate fields with the command line parameter names and description.

import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.io.File;

public class Example {
    @Option(names = { "-v", "--verbose" }, description = "Be verbose.")
    private boolean verbose = false;

    @Option(names = { "-h", "--help" }, usageHelp = true,
            description = "Displays this help message and quits.")
    private boolean helpRequested = false;

    @Parameters(arity = "1..*", paramLabel = "FILE", description = "File(s) to process.")
    private File[] inputFiles;
    ...
}

Then invoke CommandLine.populateCommand with the command line parameters and an object you want to initialize.

String[] args = { "-v", "inputFile1", "inputFile2" };
Example app = CommandLine.populateCommand(new Example(), args);

assert !app.helpRequested;
assert  app.verbose;
assert  app.inputFiles != null && app.inputFiles.length == 2;

Invoke CommandLine.usage if the user requested help or the input was invalid and a ParameterException was thrown.

CommandLine.usage(new Example(), System.out);

Usage Help with ANSI Colors and Styles

Colors, styles, headers, footers and section headings are easily customized with annotations. For example:

See the source code.

Usage Help API

Picocli annotations offer many ways to customize the usage help message.

If annotations are not sufficient, you can use picocli's Help API to customize even further. For example, your application can generate help like this with a custom layout:

See the source code.

API Changes

1.0.0

New features: command line autocompletion, Map options and parser tracing. Non-breaking changes to support Callable commands, Map options and format specifiers in version help.

0.9.8

Non-breaking changes to add better help support and better subcommand support.

0.9.7

Version 0.9.7 has some breaking API changes.

Better Groovy support

It was pointed out that Groovy had trouble distinguishing between the static parse(Object, String...) method and the instance method parse(String...).

To address this, the static parse(Object, String...) method has been renamed to populateCommand(Object, String...) in version 0.9.7.

Nested subcommands

Version 0.9.7 adds support for nested sub-subcommands
CommandLine::parse now returns List<CommandLine> (was List<Object>)
CommandLine::getCommands now returns Map<String, CommandLine> (was Map<String, Object>)
renamed method CommandLine::addCommand to addSubcommand
renamed method CommandLine::getCommands to getSubcommands

Miscellaneous

Renamed class Arity to Range since it is not just used for @Option and @Parameters arity but also for index in positional @Parameters.

RobertZenz / picocli