picocli - a mighty tiny command line interface

Picocli aims to be the easiest-to-use way to create rich command line applications that can run on and off the JVM. Considering picocli? Check what happy users say about picocli.

Picocli is a modern library and framework, written in Java, that contains both an annotations API and a programmatic API. It features 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 a native image, 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.

Picocli makes it easy to follow Command Line Interface Guidelines.

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 18-ea (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.

Unique features in picocli include support for negatable options, advanced quoted values, and argument groups. Argument groups can be used to create mutually exclusive options, mutually dependent options, option sections in the usage help message and repeating composite arguments like ([-a=<a> -b=<b> -c=<c>] (-x | -y | -z)).... For advanced use cases, applications can access the picocli command object model with the @Spec annotation, and implement custom parameter processing for option parameters if the built-in logic is insufficient.

Picocli-based applications can easily integrate with Dependency Injection containers. The Micronaut microservices framework has built-in support for picocli. Quarkus has a Command Mode with Picocli extension for facilitating the creation of picocli-based CLI applications with Quarkus. 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 examples of integrating with Guice, Spring Boot, Micronaut, Quarkus and with containers that comply to CDI 2.0 specification (JSR 365).

Releases

• All Releases
• Latest: 4.7.7 Release Notes
• Older: Picocli 4.0 Release Notes
• Older: Picocli 3.0 Release Notes
• Older: Picocli 2.0 Release Notes

Documentation

• 4.x User manual: https://picocli.info
• 4.x Quick Guide
• 4.x API Javadoc
• PREVIEW: Modular Javadoc for all artifacts (4.7.7-SNAPSHOT)
• Command line autocompletion
• Programmatic API
• FAQ
• GraalVM AOT Compilation to Native Image

Older

• ~~3.x User manual~~
• ~~3.x Quick Guide~~
• ~~3.x API Javadoc~~
• ~~2.x User manual~~
• ~~2.x API Javadoc~~
• ~~1.x User manual~~

Articles & Presentations

English

• 6 things you can do with JBang but you can’t with Shell (2022-02-28) by F.Marchioni.
• [VIDEO]Kotlin, CLIs and StarWars! - An introduction to creating CLI applications with Kotlin using Picocli (2022-02-05) by Julien Lengrand-Lambert.
• [VIDEO]Autocomplete Java CLI using Picocli (2022-01-24) by raksrahul.
• Picocli – Easiness for CLI arguments in Java (2021-10-27) by agamboa.
• Building Command Line Interfaces with Kotlin using picoCLI (2021-09-23) by Julien Lengrand-Lambert.
• [VIDEO]Create Java CLI applications with picocli (2021-09-14) by coder4life.
• PICOCLI (2021-06-30) by Sybren Boland.
• Picocli | Create your first Kotlin /JVM CLI application with GraalVM (2021-02-13) by manserpatrice.
• [VIDEO] Building kubectl plugins with Quarkus, picocli, fabric8io and jbang (2021-01-22) by Sébastien Blanc.
• [VIDEO] J-Fall Virtual 2020: Julien Lengrand - An introduction to creating CLI applications using picoCLI (2020-12-07) by Julien Lengrand-Lambert. This was the top rated talk for @nljug #jfall virtual 2020! Congrats, Julien!
• Paginate results in a command line application using picoCLI (2020-11-17) by Julien Lengrand-Lambert.
• CLI applications with GraalVM Native Image (2020-11-13) by Oleg Šelajev.
• Picocli subcommands - One program, many purposes (2020-09-22) by Jonas Andersen.
• Native CLI with Picocli and GraalVM (2020-08-20) by jbebar.
• How to build a CLI app in Java using jbang and picocli (2020-08-13) by Matthew Gilliard.
• Building a GitHub Dependents Scraper with Quarkus and Picocli (2020-07-31) by Marc Nuri.
• Building a decent Java CLI (2020-07-27) by Andreas Textor.
• [VIDEO] (Another very well-produced video by Szymon Stepniak) Implementing OAuth 2.0 in a Java command-line app using Micronaut, Picocli, and GraalVM (2020-07-23) by Szymon Stepniak (YouTube channel).
• Micronaut, Picocli, and GraalVM (2020-07-08) by Szymon Stepniak.
• [VIDEO] (Extremely well-produced and informative, recommended!) Building command-line app with Java 11, Micronaut, Picocli, and GraalVM (2020-07-01) by Szymon Stepniak (YouTube channel).
• [AUDIO] Scala Valentines #2 (2020-06-21) Podcast talks about picocli (from 18:11).
• How to create a command line tool using Java? (2020-06-18) by Vijay SRJ.
• Command-line tools with Quarkus and Picocli (2020-06-08) by [Dmytro Chaban](ht