JCommander builds a Java command-line interface from annotated fields or setter methods: register an argument object, call parse(argv), then use the populated values. It supports scalar options, repeated collections, positional arguments, dynamic key/value options, and subcommands.
Add JCommander to your project
For Maven Central’s indexed modern artifact, use org.jcommander:jcommander:3.0, which is distributed under the Apache License 2.0. The coordinates changed across releases: older versions use com.beust:jcommander. Keep the dependency coordinates and API assumptions aligned with the version used by your project. The project README associates JCommander 1.x with Java 8, 2.x with Java 11, 3.x with Java 17, and 4.x with Java 21; verify the target release’s requirements before selecting a version.
Sources: Maven Central artifact listing and JCommander project README.
Define options and parse arguments
Put the parameters in a class, annotate its fields with @Parameter, and pass an instance to JCommander. The following example accepts a verbosity level, debug switch, repeated or comma-separated groups, positional file names, and -Dkey=value properties:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →import com.beust.jcommander.JCommander;
import com.beust.jcommander.Parameter;
import com.beust.jcommander.DynamicParameter;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
class Arguments {
@Parameter(names = {"-v", "--verbosity"}, description = "Verbosity level")
int verbosity = 1;
@Parameter(names = "--debug", description = "Enable debug output")
boolean debug;
@Parameter(names = "--group", description = "Group names")
List<String> groups = new ArrayList<>();
@Parameter(description = "Input files")
List<String> files = new ArrayList<>();
@DynamicParameter(names = "-D", description = "Key/value properties")
Map<String, String> properties;
}
public class App {
public static void main(String[] argv) {
Arguments args = new Arguments();
JCommander.newBuilder()
.addObject(args)
.build()
.parse(argv);
System.out.println(args.verbosity);
System.out.println(args.groups);
System.out.println(args.files);
System.out.println(args.properties);
}
}For example, --verbosity 2 --debug --group alpha,beta --group gamma input.txt -Dmode=safe sets the verbosity to 2, enables debug, adds three group values, records input.txt as a positional value, and stores the property under mode. JCommander converts supported scalar fields such as String, int/Integer, and long/Long from their following token. Text that cannot be converted causes a parsing exception.
Source: JCommander documentation and examples.
Choose the right parameter shape
- Scalar option: Use a field such as
String,int, orlongwhen an option has one value. JCommander converts the token to the field’s supported type. - Boolean switch: A boolean parameter such as
--debugrepresents a flag. - Repeated values: Use a
ListorSetwhen an option can occur more than once. Collection parameters also accept comma-separated values. - Positional values: Use a
@Parameterfield without option names for arguments that do not begin with a named option. - Dynamic key/value entries: Use
@DynamicParameterfor forms such as-Dname=value, which populate a map.
Source: JCommander documentation.
Adjust option syntax and combine argument objects
JCommander can be configured to accept a custom separator, allowing a value to be written in a form such as -level=42 instead of -level 42. It can also register multiple objects with one parser, which is useful when separate parts of an application own different sets of options. Build the parser with each object, then call parse(argv) once.
Rank #2
Source: JCommander documentation.
Add subcommands
Register each command name and its argument object with addCommand. After parsing, call getParsedCommand() to identify the selected command, then read the corresponding command object’s populated fields.
JCommander.Builder builder = JCommander.newBuilder().addObject(globalArgs);
builder.addCommand("run", runArgs);
builder.addCommand("list", listArgs);
JCommander commander = builder.build();
commander.parse(argv);
String command = commander.getParsedCommand();
if ("run".equals(command)) {
// Use the options populated in runArgs.
} else if ("list".equals(command)) {
// Use the options populated in listArgs.
}Command metadata can be defined with @Parameters, including descriptions, aliases or command names, and whether a command is hidden from usage output.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Sources: JCommander documentation and JCommander project README.
Show usage and control parsing
Call usage() on the built parser to render help text. For example, an application can display usage when the user requests help or when it catches a parsing error. The API also exposes controls for parsing without validation, unknown-option behavior, abbreviated options, case sensitivity, overwriting parameter values, default providers, description bundles, and usage formatting. Choose these deliberately: they change how the parser treats input, so the application’s help and error handling should reflect the behavior you enable.
Rank #4
Source: JCommander API documentation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Handle invalid input and verify release compatibility
Parsing converts values into the declared field types, so malformed values can fail before application logic runs. Catch parsing exceptions at the command-line boundary and present a useful error together with usage text. When adopting or upgrading JCommander, confirm the Java baseline, Maven coordinates, and API behavior against the exact release rather than assuming that instructions for an older 1.x artifact apply unchanged to 3.x.
Sources: JCommander documentation, Maven Central artifact listing, and JCommander project README.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
