Repository files navigation

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? Checkwhat 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 withANSI colors and styles,TAB autocompletion and nested subcommands.In a single file, so you can include itin 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 anative image, with extremely fast startup time and lower memory requirements,which can be distributed as a single executable file.Picocli comes with anannotation 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 asingle line of code.Simply implementRunnable orCallable, or put the business logic of your command in a@Command-annotated method.

Picocli makes it easy to followCommand 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-likesubcommands(and nestedsub-subcommands),any option prefix style, POSIX-stylegrouped short options,customtype converters,password options and more.

Picocli distinguishes betweennamed options andpositional parameters and allowsboth to bestrongly typed.Multi-valued fields can specifyan exact number of parameters or arange (e.g.,0..*,1..2).SupportsMap options like-Dkey1=val1 -Dkey2=val2, where both key and value can be strongly typed.Parsertracing facilitates troubleshooting.Command-lineargument files (@-files) allow applications to handle very long command lines.

Generates polished and easily tailoredusage helpandversion help,usingANSI colors where possible.Requires at minimum Java 5, but is designed to facilitate the use of Java 8 lambdas. Tested on allJava versions between 5 and 18-ea (inclusive).

Picocli-based command line applications can haveTAB autocompletion,interactively showing users what options and subcommands are available.When an option hascompletionCandidates or has anenum type, autocompletion can also suggest option values.Picocli can generate completion scripts for bash and zsh, and offerspicocli-shell-jline2 andpicocli-shell-jline3 modules with JLineCompleter implementations for building interactive shell applications.

Unique features in picocli include support fornegatable options,advancedquoted values,andargument groups.Argument groups can be used to create mutuallyexclusive options,mutuallydependent options,optionsections in the usage help messageandrepeating 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, andimplementcustom parameter processing for option parameters if the built-in logic is insufficient.

Picocli-based applications can easilyintegrate with Dependency Injection containers.TheMicronaut microservices framework hasbuilt-in support for picocli.Quarkus has aCommand Mode with Picocli extension for facilitating the creation of picocli-based CLI applications with Quarkus.Picocli ships with apicocli-spring-boot-starter modulethat includes aPicocliSpringFactory and Spring Boot auto-configuration to use Spring dependency injection in your picocli command line application.The user manual has examples of integrating withGuice,Spring Boot,Micronaut,Quarkus and with containers that comply toCDI 2.0 specification (JSR 365).

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

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

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

• 6 things you can do with JBang but you can’t with Shell (2022-02-28) byF.Marchioni.
• [VIDEO]Kotlin, CLIs and StarWars! - An introduction to creating CLI applications with Kotlin using Picocli (2022-02-05) byJulien Lengrand-Lambert.
• [VIDEO]Autocomplete Java CLI using Picocli (2022-01-24) byraksrahul.
• Picocli – Easiness for CLI arguments in Java (2021-10-27) byagamboa.
• Building Command Line Interfaces with Kotlin using picoCLI (2021-09-23) byJulien Lengrand-Lambert.
• [VIDEO]Create Java CLI applications with picocli (2021-09-14) bycoder4life.
• PICOCLI (2021-06-30) bySybren Boland.
• Picocli | Create your first Kotlin /JVM CLI application with GraalVM (2021-02-13) bymanserpatrice.
• [VIDEO]Building kubectl plugins with Quarkus, picocli, fabric8io and jbang (2021-01-22) bySébastien Blanc.
• [VIDEO]J-Fall Virtual 2020: Julien Lengrand - An introduction to creating CLI applications using picoCLI (2020-12-07) byJulien 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) byJulien Lengrand-Lambert.
• CLI applications with GraalVM Native Image (2020-11-13) byOleg Šelajev.
• Picocli subcommands - One program, many purposes (2020-09-22) byJonas Andersen.
• Native CLI with Picocli and GraalVM (2020-08-20) byjbebar.
• How to build a CLI app in Java using jbang and picocli (2020-08-13) byMatthew Gilliard.
• Building a GitHub Dependents Scraper with Quarkus and Picocli (2020-07-31) byMarc Nuri.
• Building a decent Java CLI (2020-07-27) byAndreas 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) bySzymon Stepniak (YouTube channel).
• Micronaut, Picocli, and GraalVM (2020-07-08) bySzymon Stepniak.
• [VIDEO] (Extremely well-produced and informative, recommended!)Building command-line app with Java 11, Micronaut, Picocli, and GraalVM (2020-07-01) bySzymon 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) byVijay SRJ.
• Command-line tools with Quarkus and Picocli (2020-06-08) byDmytro Chaban.
• Quarkus guide forQuarkus command mode with picocli, thanks to a picocli extension byMichał Górniewski included inQuarkus 1.5 (2020-06-03).
• Native images with Micronaut and GraalVM (2020-06-01) byΛ: Olivier Revial.
• CLI applications with Micronaut and Picocli (2020-06-01) byΛ: Olivier Revial.
• Picocli introduction - Modern Java command-line parsing (2020-05-19) byJonas Andersen.
• Building Native Covid19 Tracker CLI using Java, PicoCLI & GraalVM (2020-05-11) byMohammed Aboullaite.
• Quarkus Command mode with Picocli (2020-04-27) byDmytro Chaban.
• Creating CLI tools with Scala, Picocli and GraalVM (2020-03-09) byNaoki Takezoe
• Building native Java CLIs with GraalVM, Picocli, and Gradle (2020-03-08) byMitch Seymour
• Build Great Native CLI Apps in Java with Graalvm and Picocli (2020-03-07)
• Picocli Structured Objects (2019-09-10) byPhilipp Hanslovsky explains how to use picocli's support for repeating argument groups to add or configure structured objects from the command line.
• Create a Java Command Line Program with Picocli|Baeldung (2019-05-07) byFrançois Dupire.
• A whirlwind tour of picocliJAX Magazine "Putting the spotlight on Java tools" (2019-04-08).
• An Introduction to PicoCLI (2019-02-10) bydevop.
• Corda CLI UX (User Experience) Guide (2018 by R3 Limited) gives useful advice.
• Develop a CLI tool using groovy scripts (2018-10-26) byChinthaka Dinadasa.
• Migrating from Commons CLI to picocli. You won't regret it! :-) (also on:DZone andJava Code Geeks).
• Groovy 2.5 CliBuilder Renewal (also onblogs.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 microservicesstandalone 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)

• Выбор необходимых опций Picocli на основе основного варианта (2020-05-07)
• Интерфейсы командной строки Java: picocli (2018-08-06): Russian translation byMaxRokatansky of Dustin Marx' blog post.

• picocli, un poderoso framework para la creación de aplicaciones de línea de comandos (2023-09-09) byDarkcrizt
• picocli, un poderoso framework para la creación de aplicaciones de línea de comandos (2023-09-09) byDarkcrizt
• Quarkus + Picocli: Web scaper para extraer proyectos dependientes en GitHub (2020-08-15) byMarc Nuri.
• Quarkus - Introducción: picocli (2020-06-15) byGerardo Arroyo.
• [VIDEO]Picocli - Spring Boot example (2020-05-24) 7-minute quick introduction by Gonzalo H. Mendoza.

• Application mobile: Créez de superbes applications CLI natives en Java avec Graalvm et Picocli (2020-05-07) Translation ofBuild Great Native CLI Apps in Java with Graalvm and Picocli bybouf1450.
• [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 areavailable on GitHub.

• Desenvolva aplicações CLI nativas em Java com Graalvm e Picocli (2020-08-28): Portuguese translation ofBuild Great Native CLI Apps in Java with Graalvm and Picocli, thanks toRodrigo Ap G Batista.
• [VIDEO]Quarkus #40: Command Mode com Picocli (2020-06-23): 13-minute presentation byVinícius Ferraz (@viniciusfcf).

• CLI applications with GraalVM Native Image (2020-11-21) translation byLogico_jp of Oleg Šelajev'spost.
• Picocli + Kotlin + graalvm-native-image plugin でネイティブツールを作る (2020-04-24) blog post bymike-neck (引きこもり持田 on Twitter).
• pythonのArgumentParserような使い心地！picocliのご紹介 (2020-04-15) by@astamuseLab
• Javaのコマンドラインアプリケーション向けのフレームワーク、picocliで遊ぶ (2020-03-07) blog post byかずひら.
• KuromojiのCLIコマンドとpicocliとGraalVM (2020-02-28) blog post by@johtani.
• GraalVM, PicocliとJavaでときめくネイティブコマンドラインアプリを作ろう (2019-11-23) Slides for my presentation at Japan Java User Group'sJJUG CCC 2019 Fall conference.
• Picocliを使用してJavaコマンドラインプログラムを作成する - 開発者ドキュメント (2019-10-18)
• GraalVM と Picocliで Javaのネイティブコマンドラインアプリを作ろう (2019-09-06) Slides for my lightning talk presentation at【東京】JJUG ナイトセミナー: ビール片手にLT大会 9/6（金）
• Picocli＋Spring Boot でコマンドラインアプリケーションを作成してみる (2019-07-20) byかんがるーさんの日記.
• GraalVM の native image を使って Java で爆速 Lambda の夢を見る (2019-05-02) by@kencharos

• Java命令行界面（第10部分）：picocli (2020-06-07) translation bydnc8371.
• 如何借助 Graalvm 和 Picocli 构建 Java 编写的原生 CLI 应用 (2020-03-26): Chinese translation ofBuild Great Native CLI Apps in Java with Graalvm and Picocli, thanks to张卫滨.
• 从Commons CLI迁移到Picocli (2019-03-13): Chinese translation of Migrating from Commons CLI to picocli, thanks togenghaihua.
• Picocli 2.0: Steroids上的Groovy脚本
• Picocli 2.0: 以少求多

Join thepicocli Google group if you are interested in discussing anything picocli-related and receiving announcements on new releases.

Reallinfo designed the picocli logo! Many thanks!

• 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'sCliBuilder DSL.
• Picocli is now part of Micronaut. The Micronaut CLI has been rewritten with picocli, and Micronaut has dedicated support for running microservicesstandalone with picocli. See alsoMicronaut Picocli Guide.
• Quarkus now offersCommand mode with picocli.
• Picocli is now part of JUnit 5. JUnit 5.3 migrated itsConsoleLauncher 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 alibpicocli-java package. Thanks toMiroslav Kravec.
• Picocli is used in the IntuitKarate standalone JAR / executable.
• Picocli is part ofBallerina. Ballerina uses picocli for all its command line utilities.
• Picocli is used in theCheckStyle standalone JAR / executable from Checkstyle 8.15.
• Picocli is included in theOpenJDK 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, the Apache Hive benchmark CLI, ApacheIgnite TensorFlow, and Apache SlingFeature Model Converter.
• Picocli is listed onStackShare. Please add it to your stack and add/upvote reasons why you like picocli!
• Picocli is used in Pinterestktlint.
• Picocli is used in Spring IOnohttp-cli.
• TheMinecraftPicocli library facilitates the use of picocli inMinecraft Forge.
• Simple Java Mail now offers a picocli-basedCLI.
• jbang not only uses picocli internally, but also has a CLI template to generate an initial script: usejbang --init=cli helloworld.java to generate a sample picocli-enabled jbang script. Seeasciinema.
• Picocli is the main library used in the CookieTemplecli-java template for building GraalVM native CLI executables in Java. Seethis preview.
• Picocli ismentioned inCommand Line Interface Guidelines.

Glad to see more people are using picocli. We must be doing something right. :-)

If you like picocli, help others discover picocli:

• Give picocli a star on GitHub!
• Upvote myStackOverflow answer to "How do I parse command line arguments in Java?"
• Upvote myQuora answer to "What is the best way to parse command-line arguments with Java?"

• Tweet about picocli! What do you like about it? How has it helped you? How is it different from the alternatives?
• Mention that your project uses picocli in the documentation of your project.
• Show that your GitHub project uses picocli, with this badge in your README.md:

[![picocli](https://img.shields.io/badge/picocli-4.7.6-green.svg)](https://github.com/remkop/picocli)

• Perhaps the most impactful way to show people how picocli can make their life easier is to write a blog post or article, or even do a video!

Annotate fields with the command line parameter names and description. Optionally implementRunnable orCallable to delegate error handling and requests for usage help or version help to picocli. For example:

importpicocli.CommandLine;importpicocli.CommandLine.Option;importpicocli.CommandLine.Parameters;importjava.io.File;@Command(name ="example",mixinStandardHelpOptions =true,version ="Picocli example 4.0")publicclassExampleimplementsRunnable {@Option(names = {"-v","--verbose" },description ="Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity.")privateboolean[]verbose =newboolean[0];@Parameters(arity ="1..*",paramLabel ="FILE",description ="File(s) to process.")privateFile[]inputFiles;publicvoidrun() {if (verbose.length >0) {System.out.println(inputFiles.length +" files to process...");        }if (verbose.length >1) {for (Filef :inputFiles) {System.out.println(f.getAbsolutePath());            }        }    }publicstaticvoidmain(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.intexitCode =newCommandLine(newExample()).execute(args);System.exit(exitCode);    }}

ImplementRunnable orCallable, and your command can beexecuted in one line of code. The example above uses theCommandLine.execute method to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic. Applications can callSystem.exit with the returned exit code to signal success or failure to their caller.

$ java Example -v inputFile1 inputFile22 files to process...

TheCommandLine.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 manualsection on Executing Commands for details.

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

See thesource code.

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

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

See thesource code.

You can add picocli as an external dependency to your project, or you can include it as source.See thesource code. Copy and paste it into a file calledCommandLine.java, add it to your project, and enjoy!

implementation 'info.picocli:picocli:4.7.6'

<dependency>  <groupId>info.picocli</groupId>  <artifactId>picocli</artifactId>  <version>4.7.6</version></dependency>

libraryDependencies += "info.picocli" % "picocli" % "4.7.6"

<dependency org="info.picocli" name="picocli" rev="4.7.6" />

@Grapes(    @Grab(group='info.picocli',module='picocli',version='4.7.6'))

[info.picocli/picocli "4.7.6"]

'info.picocli:picocli:jar:4.7.6'

//DEPS info.picocli:picocli:4.7.6