0
# Picocli
1
2
Picocli is a comprehensive Java command line parsing library that provides both an annotations API and a programmatic API for creating rich CLI applications. It enables developers to create professional command-line tools with minimal boilerplate code, supporting advanced features like ANSI colored help messages, TAB autocompletion, nested subcommands, argument validation, and type conversion.
3
4
## Package Information
5
6
- **Package Name**: picocli
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven: `<dependency><groupId>info.picocli</groupId><artifactId>picocli</artifactId><version>4.7.7</version></dependency>`
10
- **Gradle**: `implementation 'info.picocli:picocli:4.7.7'`
11
12
## Core Imports
13
14
```java
15
import picocli.CommandLine;
16
import picocli.CommandLine.Command;
17
import picocli.CommandLine.Option;
18
import picocli.CommandLine.Parameters;
19
```
20
21
For autocompletion:
22
23
```java
24
import picocli.AutoComplete;
25
```
26
27
## Basic Usage
28
29
### Annotation-based API
30
31
```java
32
import picocli.CommandLine;
33
import picocli.CommandLine.Command;
34
import picocli.CommandLine.Option;
35
import picocli.CommandLine.Parameters;
36
37
@Command(name = "myapp", mixinStandardHelpOptions = true, version = "1.0",
38
description = "Demonstrates picocli usage")
39
class MyApp implements Runnable {
40
41
@Option(names = {"-v", "--verbose"}, description = "Verbose output")
42
boolean verbose;
43
44
@Option(names = {"-c", "--count"}, description = "Number of iterations", defaultValue = "1")
45
int count;
46
47
@Parameters(index = "0", description = "Input file")
48
String inputFile;
49
50
@Override
51
public void run() {
52
System.out.printf("Processing %s %d times%s%n",
53
inputFile, count, verbose ? " (verbose)" : "");
54
}
55
56
public static void main(String[] args) {
57
int exitCode = new CommandLine(new MyApp()).execute(args);
58
System.exit(exitCode);
59
}
60
}
61
```
62
63
### Programmatic API
64
65
```java
66
import picocli.CommandLine;
67
import picocli.CommandLine.Model.CommandSpec;
68
import picocli.CommandLine.Model.OptionSpec;
69
70
CommandSpec spec = CommandSpec.create()
71
.name("myapp")
72
.addOption(OptionSpec.builder("-v", "--verbose")
73
.description("Verbose output")
74
.type(boolean.class)
75
.build())
76
.addOption(OptionSpec.builder("-c", "--count")
77
.description("Number of iterations")
78
.type(int.class)
79
.defaultValue("1")
80
.build());
81
82
CommandLine cmd = new CommandLine(spec);
83
CommandLine.ParseResult parseResult = cmd.parseArgs(args);
84
85
if (parseResult.hasMatchedOption("-v")) {
86
System.out.println("Verbose mode enabled");
87
}
88
```
89
90
## Architecture
91
92
Picocli is built around several key components:
93
94
- **CommandLine**: Central parsing and execution engine that coordinates all functionality
95
- **Annotation API**: Declarative approach using `@Command`, `@Option`, `@Parameters` annotations
96
- **Programmatic API**: Imperative approach using `CommandSpec`, `OptionSpec`, `PositionalParamSpec` classes
97
- **Type System**: Extensible type conversion system supporting built-in and custom converters
98
- **Help System**: Comprehensive help generation with ANSI styling and customizable sections
99
- **Execution Model**: Flexible execution strategies with built-in exception handling and exit code management
100
- **Autocompletion**: TAB completion script generation for bash and other shells
101
102
## Capabilities
103
104
### Annotations API
105
106
Declarative command definition using annotations for options, parameters, commands, and argument groups. The annotation approach provides the most concise way to define CLI interfaces.
107
108
```java { .api }
109
@Command(name = "mycommand", description = "Command description")
110
public class MyCommand implements Runnable {
111
@Option(names = {"-v", "--verbose"}, description = "Enable verbose output")
112
boolean verbose;
113
114
@Parameters(index = "0", description = "Input file")
115
String inputFile;
116
}
117
```
118
119
[Annotations](./annotations.md)
120
121
### CommandLine Core
122
123
Central command line parsing and execution functionality including argument parsing, subcommand handling, configuration options, and execution strategies.
124
125
```java { .api }
126
public class CommandLine {
127
public CommandLine(Object command);
128
public CommandLine(Object command, IFactory factory);
129
130
public int execute(String... args);
131
public ParseResult parseArgs(String... args);
132
public CommandLine addSubcommand(String name, Object command);
133
}
134
```
135
136
[CommandLine Core](./command-line.md)
137
138
### Help System
139
140
Comprehensive help generation system with ANSI styling, customizable sections, and usage message formatting. Supports both automatic help generation and custom help rendering.
141
142
```java { .api }
143
public static class Help {
144
public Help(CommandSpec commandSpec);
145
public String fullSynopsis();
146
public String detailedSynopsis(int synopsisHeadingLength, Comparator<OptionSpec> optionSort, boolean clusterOptions);
147
}
148
149
public static void usage(Object command, PrintStream out);
150
public static void usage(Object command, PrintStream out, Help.Ansi ansi);
151
```
152
153
[Help System](./help-system.md)
154
155
### Parsing and Execution
156
157
Parse result handling, execution strategies, and exception management for robust command line processing with detailed error reporting.
158
159
```java { .api }
160
public static class ParseResult {
161
public boolean hasMatchedOption(String option);
162
public <T> T matchedOptionValue(String option, T defaultValue);
163
public List<String> matchedPositionalValue(int index, List<String> defaultValue);
164
}
165
166
public interface IExecutionStrategy {
167
int execute(ParseResult parseResult) throws ExecutionException;
168
}
169
```
170
171
[Parsing and Execution](./parsing-execution.md)
172
173
### Type Conversion
174
175
Extensible type conversion system for converting string command line arguments to strongly typed Java objects, with built-in converters and custom converter support.
176
177
```java { .api }
178
public interface ITypeConverter<K> {
179
K convert(String value) throws Exception;
180
}
181
182
public interface IDefaultValueProvider {
183
String defaultValue(ArgSpec argSpec) throws Exception;
184
}
185
```
186
187
[Type Conversion](./type-conversion.md)
188
189
### Autocompletion
190
191
TAB completion script generation and completion candidate suggestion for creating shell autocompletion functionality.
192
193
```java { .api }
194
public class AutoComplete {
195
public static void main(String... args);
196
public static String bash(String scriptName, CommandLine commandLine);
197
public static int complete(CommandSpec spec, String[] args, int argIndex, int positionInArg, int cursor, List<CharSequence> candidates);
198
}
199
```
200
201
[Autocompletion](./autocompletion.md)
202
203
## Common Types
204
205
```java { .api }
206
public static final class ExitCode {
207
public static final int OK = 0;
208
public static final int SOFTWARE = 1;
209
public static final int USAGE = 2;
210
}
211
212
public enum TraceLevel { OFF, WARN, INFO, DEBUG }
213
214
public enum ScopeType { LOCAL, INHERIT }
215
216
public static class Help {
217
public enum Ansi { AUTO, ON, OFF }
218
219
public enum Visibility { ALWAYS, NEVER, ON_DEMAND }
220
221
public static class ColorScheme {
222
public ColorScheme(Ansi ansi);
223
public Ansi ansi();
224
}
225
}
226
227
public static class Range implements Comparable<Range> {
228
public Range(int min, int max);
229
public int min();
230
public int max();
231
public boolean contains(int value);
232
public static Range valueOf(String range);
233
}
234
```