Picocli — Powerful CLI Framework for Java and the JVM

Introduction

Picocli is a modern command-line interface framework for JVM applications that uses annotations to define commands, options, and positional parameters. It generates usage help with ANSI colors, supports TAB autocompletion, and produces native executables via GraalVM, all from a single source file with zero external dependencies.

What Picocli Does

• Parses command-line arguments using declarative annotations on Java classes and fields
• Generates colored usage help text automatically from annotations and descriptions
• Supports nested subcommands, argument groups, and mutually exclusive options
• Provides TAB autocompletion scripts for Bash, Zsh, and Fish shells
• Compiles to native executables via GraalVM for instant startup

Architecture Overview

Picocli is a single Java source file (~90K lines) that can be included directly in projects to avoid adding a dependency. At runtime, it uses reflection to inspect annotated classes, builds an argument specification model, and parses the command-line token array against it. Type conversion is handled by built-in converters for common types (files, URLs, enums, dates) and extensible custom converters. The help renderer formats usage text with ANSI escape codes and word wrapping. For GraalVM native images, picocli provides a compile-time annotation processor that generates reflection configuration automatically.

Self-Hosting & Configuration

• Add as a single Maven or Gradle dependency, or copy the source file directly into your project
• Annotate command classes with @Command and fields with @Option or @Parameters
• Generate completion scripts with picocli.AutoComplete and install them in the user's shell
• Configure ANSI color themes through system properties or annotation attributes
• Use the picocli-codegen module for GraalVM native image reflection configuration

Key Features

• Zero-dependency design: a single source file that can be vendored to avoid dependency management
• ANSI-colored usage help with customizable layout, headers, and footers
• Type conversion for 40+ built-in types including files, enums, dates, and network addresses
• Execution model with @Command classes implementing Runnable or Callable for structured return codes
• GraalVM native image support with automatic reflection configuration generation

Comparison with Similar Tools

• Apache Commons CLI — basic argument parsing without annotations; Picocli adds declarative configuration and rich help output
• JCommander — annotation-based like Picocli but with less colorful help and no autocompletion
• Airline — supports Git-style subcommands; Picocli offers a more comprehensive feature set in a single file
• Clikt (Kotlin) — Kotlin-first CLI framework; Picocli works across all JVM languages
• Cobra (Go) — the Go equivalent; Picocli brings similar power to the JVM ecosystem

FAQ

Q: Can I use Picocli with Kotlin or Scala? A: Yes. Picocli works with any JVM language. Kotlin examples and extensions are included in the documentation.

Q: How do I distribute a native CLI binary? A: Compile your Picocli application with GraalVM native-image. Picocli's annotation processor generates the required reflection metadata automatically.

Q: Does Picocli support environment variable fallbacks? A: Yes. Use the defaultValue attribute with ${env:VAR_NAME} syntax to fall back to environment variables.

Q: What is the startup time for a native image? A: GraalVM native images built with Picocli typically start in under 10 milliseconds, compared to hundreds of milliseconds for JVM startup.

Sources

• https://github.com/remkop/picocli
• https://picocli.info/