Java command line parser with both an annotations API and a programmatic API, featuring usage help with ANSI colors and styles, TAB autocompletion 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.
Picocli-based applications can be ahead-of-time compiled to
native images, with extremely fast startup time and lower memory requirements,
which can be distributed as a single executable file.
Picocli comes with an annotation processor that automatically Graal-enables your jar during compilation.
Picocli applications can be very compact with no boilerplate code: your command (or subcommand) can be executed with a single line of code.
Simply implement Runnable
or Callable
, or put the business logic of your command in a @Command
-annotated method.
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, password options and more.
Picocli 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.
Parser tracing facilitates troubleshooting.
Command-line argument files (@-files) allow applications to handle very long command lines.
Generates polished and easily tailored usage help and version help, using ANSI colors where possible. Requires at minimum Java 5, but is designed to facilitate the use of Java 8 lambdas. Tested on all Java versions between 5 and 14 (inclusive).
Picocli-based command line applications can have TAB autocompletion,
interactively showing users what options and subcommands are available.
When an option has completionCandidates
or has an enum
type, autocompletion can also suggest option values.
Picocli can generate completion scripts for bash and zsh, and offers picocli-shell-jline2
and picocli-shell-jline3
modules with JLine Completer
implementations for building interactive shell applications.
Picocli-based applications can easily integrate with Dependency Injection containers.
The Micronaut microservices framework has built-in support for picocli.
Picocli ships with a picocli-spring-boot-starter
module
that includes a PicocliSpringFactory
and Spring Boot auto-configuration to use Spring dependency injection in your picocli command line application.
The user manual has an example of integrating with Guice.
- All Releases
- Latest: 4.0.3 Release Notes
- Older: Picocli 4.0 Release Notes
- Older: Picocli 3.0 Release Notes
- Older: Picocli 2.0 Release Notes
- 4.x User manual: https://picocli.info
- 4.x Quick Guide
- 4.x API Javadoc
- Command line autocompletion
- Programmatic API
- FAQ
- GraalVM AOT Compilation to Native Image
- Create a Java Command Line Program with Picocli|Baeldung (2019-05-07) by François Dupire.
- A whirlwind tour of picocli JAX Magazine "Putting the spotlight on Java tools" (2019-04-08).
- An Introduction to PicoCLI (2019-02-10) by devop.
- Develop a CLI tool using groovy scripts (2018-10-26) by Chinthaka Dinadasa.
- Migrating from Commons CLI to picocli. You won't regret it! :-) (also on: DZone and Java Code Geeks).
- Groovy 2.5 CliBuilder Renewal (also on blogs.apache.org). In two parts: Part 1 (also on: DZone, Java Code Geeks), Part 2 (also on: DZone, Java Code Geeks).
- Micronaut user manual for running microservices standalone with picocli.
- Java Command-Line Interfaces (Part 30): Observations by Dustin Marx about picocli 2.0.1 (also on: DZone, Java Code Geeks)
- Java Command-Line Interfaces (Part 10): Picocli by Dustin Marx about picocli 0.9.7 (also on: DZone, Java Code Geeks)
- Picocli 2.0: Groovy Scripts on Steroids (also on: DZone, Java Code Geeks)
- Picocli 2.0: Do More With Less (also on: DZone, Java Code Geeks)
- Announcing picocli 1.0 (also on: DZone)
- Интерфейсы командной строки Java: picocli (2018-08-06): Russian translation by MaxRokatansky of Dustin Marx' blog post.
- [VIDEO] Des applications en ligne de commande avec Picocli et GraalVM (N. Peters) (2019-05-07): 15 minute presentation by Nicolas Peters during Devoxx FR. Presentation slides are available on GitHub.
- Picocli+Spring Boot でコマンドラインアプリケーションを作成してみる (2019-07-20) by かんがるーさんの日記.
- GraalVM の native image を使って Java で爆速 Lambda の夢を見る (2019-05-02) by @kencharos
- 从Commons CLI迁移到Picocli (2019-03-13): Chinese translation of Migrating from Commons CLI to picocli, thanks to genghaihua.
- Picocli 2.0: Steroids上的Groovy脚本
- Picocli 2.0: 以少求多
Join the picocli Google group if you are interested in discussing anything picocli-related and receiving announcements on new releases.
Reallinfo designed the new picocli logo! Many thanks!
This project follows semantic versioning and adheres to the Zero Bugs Commitment. |
---|
- Picocli is now part of Groovy. From Groovy 2.5, all Groovy command line tools are picocli-based, and picocli is the underlying parser for Groovy's CliBuilder DSL.
- Picocli is now part of Micronaut. The Micronaut CLI has been rewritten with picocli, and Micronaut has dedicated support for running microservices standalone with picocli.
- Picocli is now part of JUnit 5. JUnit 5.3 migrated its
ConsoleLauncher
from jopt-simple to picocli to support @-files (argument files); this helps users who need to specify many tests on the command line and run into system limitations. - Debian now offers a libpicocli-java package. Thanks to Miroslav Kravec.
- Picocli is used in the Intuit Karate standalone JAR / executable.
- Picocli is part of Ballerina. Ballerina uses picocli for all its command line utilities.
- Picocli is used in the CheckStyle standalone JAR / executable from Checkstyle 8.15.
- Picocli is included in the OpenJDK Quality Outreach list of Free Open Source Software (FOSS) projects that actively test against OpenJDK builds.
- Picocli is used in the Apache Hadoop Ozone/HDDS command line tools.
- Picocli is used in the Apache Hive benchmark CLI.
- Picocli is listed on StackShare. Please add it to your stack and add/upvote reasons why you like picocli!
Glad to see more people are using picocli. We must be doing something right. :-)
If you like picocli and your project is on GitHub, consider adding this badge to your README.md:
[![picocli](https://img.shields.io/badge/picocli-4.0.3-green.svg)](https://github.com/remkop/picocli)
Annotate fields with the command line parameter names and description. Optionally implement Runnable
or Callable
to delegate error handling and requests for usage help or version help to picocli. For example:
import picocli.CommandLine;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.io.File;
@Command(name = "example", mixinStandardHelpOptions = true, version = "Picocli example 4.0")
public class Example implements Runnable {
@Option(names = { "-v", "--verbose" },
description = "Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity.")
private boolean[] verbose = new boolean[0];
@Parameters(arity = "1..*", paramLabel = "FILE", description = "File(s) to process.")
private File[] inputFiles;
public void run() {
if (verbose.length > 0) {
System.out.println(inputFiles.length + " files to process...");
}
if (verbose.length > 1) {
for (File f : inputFiles) {
System.out.println(f.getAbsolutePath());
}
}
}
public static void main(String[] args) {
// By implementing Runnable or Callable, parsing, error handling and handling user
// requests for usage help or version help can be done with one line of code.
int exitCode = new CommandLine(new Example()).execute(args);
System.exit(exitCode);
}
}
Implement Runnable
or Callable
, and your command can be executed in one line of code. The example above uses the CommandLine.execute
method to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic. Applications can call System.exit
with the returned exit code to signal success or failure to their caller.
$ java Example -v inputFile1 inputFile2
2 files to process...
The CommandLine.execute
method automatically prints the usage help message if the user requested help or when the input was invalid.
This can be customized in many ways. See the user manual section on Executing Commands for details.
Colors, styles, headers, footers and section headings are easily customized with annotations. For example:
See the source code.
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.
You can add picocli as an external dependency to your project, or you can include it as source.
See the source code. Copy and paste it into a file called CommandLine.java
, add it to your project, and enjoy!
compile 'info.picocli:picocli:4.0.3'
<dependency>
<groupId>info.picocli</groupId>
<artifactId>picocli</artifactId>
<version>4.0.3</version>
</dependency>
libraryDependencies += "info.picocli" % "picocli" % "4.0.3"
<dependency org="info.picocli" name="picocli" rev="4.0.3" />
@Grapes(
@Grab(group='info.picocli', module='picocli', version='4.0.3')
)
[info.picocli/picocli "4.0.3"]
'info.picocli:picocli:jar:4.0.3'