picocli - a mighty tiny command line interface
A Java command line parsing framework 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.
How it works: annotate your class and picocli initializes it from the command line arguments, converting the input to strongly typed data. Supports subcommands (and nested sub-subcommands), any option prefix style, POSIX-style grouped short options, custom type converters and more.
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
).
Generates polished and easily tailored usage help, using ANSI colors where possible. Works with Java 5 or higher (but is designed to facilitate the use of Java 8 lambdas).
- user manual: http://picocli.info
- API Javadoc
- FAQ
- Releases
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" }, help = 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);
Polishing Usage Help
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
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 returnsList<CommandLine>
(wasList<Object>
)CommandLine::getCommands
now returnsMap<String, CommandLine>
(wasMap<String, Object>
)- renamed method
CommandLine::addCommand
toaddSubcommand
- renamed method
CommandLine::getCommands
togetSubcommands
Miscellaneous
Renamed class Arity
to Range
since it is not just used for @Option and @Parameters arity
but also for index
in positional @Parameters.