Home

Awesome

<p align="center"><img src="docs/images/logo/horizontal-400x150.png" alt="picocli" height="150px"></p>

GitHub Release Maven Central GitHub Actions Build Status Tests codecov Follow @remkopopma Follow @picocli Follow picocli on StackShare

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 <img src="https://www.graalvm.org/resources/img/logo-colored.svg" alt="GraalVM"> 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.

<a id="picocli_demo"></a> Picocli Demo help message with ANSI colors

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

Documentation

Older

Articles & Presentations

English

русский

Español

Français

Português

日本語

中文

Mailing List

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

Credit

<img src="https://picocli.info/images/logo/horizontal-400x150.png" height="100">

Reallinfo designed the picocli logo! Many thanks!

Commitments

This project follows semantic versioning and adheres to the Zero Bugs Commitment.

Adoption

<div> <img src="https://picocli.info/images/groovy-logo.png" height="50"> <!--groovy--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://objectcomputing.com/files/3416/2275/4315/micronaut_horizontal_black.svg" height="50"><!--micronaut--><img src="https://picocli.info/images/1x1.png" width="10"><img src="https://avatars.githubusercontent.com/u/47638783?s=200&v=4" height="50"><!--quarkus--><img src="https://picocli.info/images/1x1.png" width="10"><img src="https://picocli.info/images/junit5logo-172x50.png" height="50"><!--junit5--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://picocli.info/images/debian-logo-192x50.png" height="50"> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/8433081?s=200&v=4" height="50"><!--intel--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/4430336?s=200&v=4" height="50"><!--oracle--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/1666512?s=200&v=4" height="50"><!--JOOQ--> <img src="https://picocli.info/images/1x1.png" width="10"><img src="https://avatars.githubusercontent.com/u/545988?s=200&v=4" height="50"><!--SonarSource--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/47359?s=200&v=4" height="50"><!--Apache--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/3287599?s=200&v=4" height="50"><!--ESA--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/438548?s=200&v=4" height="50"><!--Liquibase--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/8976946?s=200&v=4" height="50"><!--Harvard PL--> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://avatars.githubusercontent.com/u/2810941?s=200&v=4" height="50"><!--Google Cloud services--> <img src="https://picocli.info/images/1x1.png" width="10">

<img src="https://avatars.githubusercontent.com/u/317776?s=200&v=4" height="50"><!--Spring--> <img src="https://avatars0.githubusercontent.com/u/3299148?s=200&v=4" height="50"> <img src="https://avatars3.githubusercontent.com/u/39734771?s=200&v=4" height="50"> <img src="https://avatars3.githubusercontent.com/u/1453152?s=200&v=4" height="50"> <img src="https://avatars1.githubusercontent.com/u/201120?s=200&v=4" height="50"> <img src="https://avatars0.githubusercontent.com/u/6154722?s=200&v=4" height="50"> <img src="https://avatars3.githubusercontent.com/u/453694?s=200&v=4" height="50"> <img src="https://avatars0.githubusercontent.com/u/82592?s=200&v=4" height="50"> <img src="https://avatars0.githubusercontent.com/u/9312489?s=200&v=4" height="50"> <img src="https://avatars0.githubusercontent.com/u/59439283?s=200&v=4" height="50"> <img src="https://avatars1.githubusercontent.com/u/4186383?s=200&v=4" height="50"> <img src="https://redis.com/wp-content/uploads/2021/08/redis-logo.png" height="50"> <img src="https://picocli.info/images/karate-logo.png" height="50" width="50"/> <img src="https://picocli.info/images/checkstyle-logo-260x50.png" height="50"><img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://picocli.info/images/ballerina-logo.png" height="40"><img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://picocli.info/images/apache-hive-logo.png" height="50"><img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://hadoop.apache.org/hadoop-logo.jpg" height="50"><img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://picocli.info/images/apache-ozone-logo.png" height="50"> <img src="https://picocli.info/images/1x1.png" width="10"> <img src="https://picocli.info/images/stackshare-logo.png" height="50"> <img src="https://ignite.apache.org/images/Ignite_tm_Logo_blk_RGB.svg" height="50"> <img src="https://camo.githubusercontent.com/501aae78d282faf7a904bbb92f46eb8d19445ad5/687474703a2f2f736c696e672e6170616368652e6f72672f7265732f6c6f676f732f736c696e672e706e67" height="50"> <img src="https://avatars1.githubusercontent.com/u/541152?s=200&v=4" height="50"> <img src="https://camo.qiitausercontent.com/ec81e80366e061c8488b25c013003267b7a578d4/68747470733a2f2f71696974612d696d6167652d73746f72652e73332e616d617a6f6e6177732e636f6d2f302f3939352f33323331306534352d303537332d383534322d373035652d6530313138643434323632302e706e67" height="50"> <img src="https://mk0upserved13l70iwek.kinstacdn.com/media/Upserve_LS_Lockup_000000_RGB_Vertical.svg" height="50"> <img src="https://www.kloudtek.com/logo-dark.png" height="50"> <img src="https://www.schemacrawler.com/images/schemacrawler_logo.svg" height="50"> <img src="https://avatars1.githubusercontent.com/u/22600631?s=200&v=4" height="50"> <img src="https://fisco-bcos-documentation.readthedocs.io/en/latest/_static/images/FISCO_BCOS_Logo.svg" height="50"> <img src="https://avatars0.githubusercontent.com/u/35625214?s=200&v=4" height="50"> <img src="https://avatars1.githubusercontent.com/u/2386734?s=200&v=4" height="50"> <img src="https://www.e-contract.be/images/logo.svg" height="50"> <img src="https://present.co/images/logn-new@2x.png" height="50"> <img src="https://avatars2.githubusercontent.com/u/13641167?s=200&v=4" height="50"> <img src="https://concord.walmartlabs.com/assets/img/logo.png" height="50"> <img src="https://res-3.cloudinary.com/crunchbase-production/image/upload/c_lpad,h_120,w_120,f_auto,b_white,q_auto:eco/etxip1k2sx4sphvwgkdu" height="50"> <img src="https://avatars.githubusercontent.com/u/1390178?s=200&v=4" height="50"><!-- minecraft forge-->

</div> <img src="https://picocli.info/images/downloads-202011.png">

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

Contribute by helping to promote picocli

If you like picocli, help others discover picocli:

Easy and impactful :sweat_smile:

Spread the joy! :tada:

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

Preach it! :muscle:

Example

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.

Usage help message with ANSI colors

This can be customized in many ways. See the user manual section on Executing Commands for details.

Usage Help with ANSI Colors and Styles

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

Longer help message with ANSI colors

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:

Usage help message with two options per row

See the source code.

Download

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!

Gradle

implementation 'info.picocli:picocli:4.7.6'

Maven

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

Scala SBT

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

Ivy

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

Grape

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

Leiningen

[info.picocli/picocli "4.7.6"]

Buildr

'info.picocli:picocli:jar:4.7.6'

JBang

//DEPS info.picocli:picocli:4.7.6