Skip to content

Latest commit

 

History

History
200 lines (151 loc) · 11.7 KB

README.md

File metadata and controls

200 lines (151 loc) · 11.7 KB
Raw

picocli

GitHub Release Build Status codecov Follow @remkopopma Follow @picocli

picocli - a mighty tiny command line interface

Java command line parser with both an annotations API and a programmatic API, featuring usage help with ANSI colors, autocomplete 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.

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. Parser tracing facilitates troubleshooting.

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.

Generates polished and easily tailored usage help and version help, using ANSI colors where possible. Works with Java 5 or higher (but is designed to facilitate the use of Java 8 lambdas).

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 an API to easily create a JLine Completer for your application.

Picocli-based applications can easily integrate with Dependency Injection containers.

Picocli Demo help message with ANSI colors

Releases

Documentation

Articles

Related

Credit

Reallinfo designed the new picocli logo! Many thanks!

Adoption

  • 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.

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

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 3.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) {
        CommandLine.run(new Example(), System.out, args);
    }
}

If your command implements Runnable, all the code that is necessary to parse the command line and execute the command is a call to CommandLine.run with the command line parameters and the Runnable command. When the program is run on the command line, the command line arguments are converted to Java objects and assigned to the annotated fields. After the arguments are successfully parsed, picocli calls the command's run method.

$ java Example -v inputFile1 inputFile2

2 files to process...

The CommandLine.run convenience method automatically prints the usage help message if the user requested help or when the input was invalid.

Usage help message with ANSI colors

If you want more control, you may be interested in the CommandLine.parse or CommandLine.parseWithHandlers methods. See the user manual 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

compile 'info.picocli:picocli:3.5.2'

Maven

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

Scala SBT

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

Ivy

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

Grape

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

Leiningen

[info.picocli/picocli "3.5.2"]

Buildr

'info.picocli:picocli:jar:3.5.2'