Docs navigation
Core
Build Plugins
AI
Dev & Test
Build
Data Access
Database Migration
Errors
Messaging
Analytics
API
Cloud
Configuration
Languages
Misc
Reactive
Views
Validation
Configuration Reference
On this page

Picocli

1 Introduction

Picocli is a command line parser that supports usage help with ANSI colors, autocomplete and nested subcommands. It has an annotations API to create command line applications with almost no code, and a programmatic API for dynamic uses like creating Domain Specific Languages.

From the project Readme page:

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, password options, custom type converters and more. Parser tracing facilitates troubleshooting.

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

It generates polished and easily tailored usage help and version help, using ANSI colors where possible. Picocli-based command line applications can have TAB autocompletion, interactively showing users what options and subcommands are available. Picocli can generate completion scripts for bash and zsh, and offers an API to easily create a JLine Completer for your application.

Micronaut features dedicated support for defining picocli Command instances. Micronaut applications built with picocli can be deployed with or without the presence of an HTTP server.

Combining picocli with Micronaut makes it easy to provide a rich, well-documented command line interface for your Microservices.

2 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-picocli/releases

3 Create Micronaut Picocli app

You can create a Micronaut command line interface application using the Micronaut CLI:

Example 1. Using the CLI
$ mn create-cli-app my-app

or with Micronaut Launch

launch

4 Setting up Picocli

To add support for Picocli to an existing project, you should first add the picocli dependency and the Micronaut picocli configuration to your build configuration.

implementation("io.micronaut.picocli:micronaut-picocli")

The picocli-codegen module includes an annotation processor that can build a model from the picocli annotations at compile time rather than at runtime. Enabling this annotation processor in your project is optional, but recommended.

annotationProcessor("info.picocli:picocli-codegen")
Note
 The picocli-codegen annotation processor is incompatible with the Kotlin KSP compiler plugin. Using it in a Kotlin project requires the Kotlin Kapt compiler plugin instead.

Configuring picocli

Picocli does not require configuration. See other sections of the manual for configuring the services and resources to inject.

5 Generating a Picocli Project

To create a project with picocli support using the Micronaut CLI, use the create-cli-app command. This will add the dependencies for the picocli feature, and set the applicationType of the generated project to cli, so the create-command command is available to generate additional commands.

The main class of the project is set to the *Command class (based on the project name - e.g., hello-world will generate HelloWorldCommand):

$ mn create-cli-app my-cli-app

The generated command looks like this:

my.cli.app.MyCliAppCommand.java generated by create-cli-app
import io.micronaut.configuration.picocli.PicocliRunner;
import org.slf4j.Logger;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

import static org.slf4j.LoggerFactory.getLogger;

@Command(name = "my-cli-app", description = "...", mixinStandardHelpOptions = true) // 
public class MyCliAppCommand implements Runnable { // 
    private static final Logger LOG = getLogger(MyCliAppCommand.class);

    @Option(names = {"-v", "--verbose"}, description = "...") // 
    boolean verbose;

    public static void main(String[] args) throws Exception {
        PicocliRunner.run(MyCliAppCommand.class, args); // 
    }

    public void run() { // 
        // business logic here
        if (verbose) {
            LOG.info("Hi!");
        }
    }
}

  1. The picocli @Command annotation designates this class as a command. The mixinStandardHelpOptions attribute adds --help and --version options to it.

  2. By implementing Runnable or Callable your application can be executed in a single line (<4>) and picocli takes care of handling invalid input and requests for usage help (<cmd> --help) or version information (<cmd> --version).

  3. An example option. Options can have any name and be of any type. The generated code contains this example boolean flag option that lets the user request more verbose output.

  4. PicocliRunner lets picocli-based applications leverage the Micronaut DI container. PicocliRunner.run first creates an instance of this command with all services and resources injected, then parses the command line, while taking care of handling invalid input and requests for usage help or version information, and finally invokes the run method.

  5. Put the business logic of the application in the run or call method.

Running the Application

Now you can build the project and start the application. Generate an executable Jar. When you run this JAR, it executes the MyCliAppCommand command.

With Gradle:

$ ./gradlew shadowJar
$ java -jar build/libs/my-cli-app-0.1-all.jar -v

With Maven Package:

$ ./mvnw package
$ java -jar target/my-cli-app-0.1.jar -v

6 Picocli Quick Start

Creating a Picocli Command with @Command

This section will show a quick example that provides a command line interface to a HTTP client that communicates with the GitHub API.

When creating this example project with the Micronaut CLI, use the create-cli-app command, and add the --features=http-client flag:

$ mn create-cli-app example.git-star --features http-client

This will add the io.micronaut:micronaut-http-client dependency to the build. You can also manually add to your build:

implementation("io.micronaut.picocli:micronaut-http-client")

An Example HTTP Client

To create a picocli Command you create a class with fields annotated with @Option or @Parameters to capture the values of the command line options or positional parameters, respectively.

For example the following is a picocli @Command that wraps around the GitHub API:

Example picocli command with injected HTTP client
import io.micronaut.configuration.picocli.PicocliRunner;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import jakarta.inject.Inject;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;

import java.util.Arrays;
import java.util.List;
import java.util.Map;

@Command(name = "git-star", header = {
    "@|green       _ _      _             |@", // 
    "@|green  __ _(_) |_ __| |_ __ _ _ _  |@",
    "@|green / _` | |  _(_-<  _/ _` | '_| |@",
    "@|green \\__, |_|\\__/__/\\__\\__,_|_|@",
    "@|green |___/                        |@"},
    description = "Shows GitHub stars for a project",
    mixinStandardHelpOptions = true,
    version = "git-star 0.1") // 
public class GitStarCommand implements Runnable {

    @Client("https://api.github.com")
    @Inject
    HttpClient client; // 

    @Option(names = { "-v", "--verbose" }, description = "Shows some project details")
    boolean verbose;

    @Parameters(  // 
        description = {
            "One or more GitHub slugs (comma separated) to show stargazers for. Default: ${DEFAULT-VALUE}"
        },
        split = ",",
        paramLabel = "<owner/repo>"
    )
    List<String> githubSlugs = Arrays.asList("micronaut-projects/micronaut-core", "remkop/picocli");

    public void run() { // 
        BlockingHttpClient blockingClient = client.toBlocking();
        for (String slug : githubSlugs) {
            HttpRequest<Object> httpRequest = HttpRequest.GET("/repos/" + slug)
                .header("User-Agent", "remkop-picocli");
            Map<?,?> m = blockingClient.retrieve(httpRequest, Map.class);
            System.out.printf("%s has %s stars%n", slug, m.get("watchers"));

            if (verbose) {
                String msg = "Description: %s%nLicense: %s%nForks: %s%nOpen issues: %s%n%n";
                System.out.printf(msg, m.get("description"),
                    ((Map<?,?>) m.get("license")).get("name"),
                    m.get("forks"), m.get("open_issues"));
            }
        }
    }

    public static void main(String[] args) {
        int exitCode = PicocliRunner.execute(GitStarCommand.class, args);
        System.exit(exitCode);
    }
}

  1. Headers, footers and descriptions can be multi-line. You can embed ANSI styled text anywhere with the @|STYLE1[,STYLE2]…​ text|@ markup notation.

  2. Add version information to display when the user requests this with --version. This can also be supplied dynamically, e.g. from the manifest file or a build-generated version properties file.

  3. Inject a HTTP client. In this case, hard-coded to the GitHub API endpoint.

  4. A positional parameter that lets the user select one or more GitHub projects

  5. The business logic: display information for each project the user requested.

The usage help message generated for this command looks like this:

picocli example

7 Subcommands

If your service has a lot of functionality, a common pattern is to have subcommands to control different areas of the service. To allow Micronaut to inject services and resources correctly into the subcommands, make sure to obtain subcommand instances from the ApplicationContext, instead of instantiating them directly.

The easiest way to do this is to declare the subcommands on the top-level command, like this:

A top-level command with subcommands
import picocli.CommandLine.Command;
import io.micronaut.configuration.picocli.PicocliRunner;

import java.util.concurrent.Callable;

@Command(name = "topcmd", subcommands = {SubCmd1.class, SubCmd2.class}) // 
public class TopCommand implements Callable<Object> { // 

    public static void main(String[] args) {
        PicocliRunner.execute(TopCommand.class, args); // 
    }

    @Override
    public Object call() throws Exception {
        return "Hi Top Command!";
    }
}

@Command(name = "subcmd1")
class SubCmd1 implements Callable<Object> { // 

    @Override
    public Object call() throws Exception {
        return "Hi Sub Command 1!";
    }
}

@Command(name = "subcmd2")
class SubCmd2 implements Callable<Object> { // 

    @Override
    public Object call() throws Exception {
        return "Hi Sub Command 2!";
    }
}

  1. The top-level command has two subcommands, SubCmd1 and SubCmd2.

  2. Let all commands in the hierarchy implement Runnable or Callable.

  3. Start the application with PicocliRunner. This creates an ApplicationContext that instantiates the commands and performs the dependency injection.

8 Customizing Picocli

Occasionally you may want to set parser options or otherwise customize picocli behavior. This can easily be done via the setter methods on the picocli CommandLine object, but the PicocliRunner does not expose that object.

In such cases, you may want to invoke picocli directly instead of using the PicocliRunner. The code below demonstrates how to do this:

Example of customizing the picocli parser before invoking a command
import io.micronaut.configuration.picocli.MicronautFactory;
import io.micronaut.context.ApplicationContext;
import io.micronaut.context.env.Environment;
import picocli.CommandLine;
import picocli.CommandLine.*;
import java.util.concurrent.Callable;

@Command(name = "configuration-example")
public class ConfigDemo implements Callable<Object> {
    private static int execute(Class<?> clazz, String[] args) {
        try (ApplicationContext context = ApplicationContext.builder(
            clazz, Environment.CLI).start()) { // 

            return new CommandLine(clazz, new MicronautFactory(context)). // 
                setCaseInsensitiveEnumValuesAllowed(true). // 
                setUsageHelpAutoWidth(true). // 
                execute(args); // 
        }
    }

    public static void main(String[] args) {
        int exitCode = execute(ConfigDemo.class, args);
        System.exit(exitCode); // 
    }

    @Override
    public Object call() {
        return "Hi!";
    }
}

  1. Instantiate a new ApplicationContext for the CLI environment, in a try-with-resources statements, so that the context is automatically closed before the method returns.

  2. Pass a MicronautFactory with the application context to the picocli CommandLine constructor. This enables dependencies to be injected into the command and subcommands.

  3. An example of configuring the picocli command line parser.

  4. An example of configuring the picocli usage help message.

  5. Execute the command and return the result (this closes the application context).

  6. Optionally call System.exit with the returned exit code.

9 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-picocli