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
```