JCommander Documentation

When a field is of type List or Set, JCommander allows the parameter to occur multiple times or be provided as a comma-separated list.

• Multiple occurrences: -host host1 -host host2
• Comma-separated: -hosts host1,host2

JCommander uses annotations to map command-line arguments to class fields:

• @Parameter: Used for standard arguments.
  • names: An array of strings or a single string representing the flag (e.g., names = { "-log", "-verbose" } or names = "-groups").
  • description: A string describing the parameter.
  • placeholder: A string used in help documentation to show the expected format.
  • Unnamed @Parameter fields capture remaining positional arguments into a List.
• @DynamicParameter: Used for key-value pairs where the key is provided at runtime (e.g., -Dkey=value). This typically maps to a Map<String, String>.

JCommander handles boolean types in two ways based on the arity attribute:

1. Arity 0 (Default): If the field is boolean or Boolean, it acts as a flag. If the option is present on the command line, the field is set to true. No additional value is required.
2. Arity 1: If you set arity = 1, the user must explicitly provide a value (e.g., true or false).

// Arity 0: Flag style
@Parameter(names = "-debug", description = "Debug mode")
private boolean debug = false;

// Arity 1: Explicit value required
@Parameter(names = "-debug", description = "Debug mode", arity = 1)
private boolean debug = true;

JCommander allows you to parse command line arguments by annotating fields in a Java class with @Parameter. You then use the JCommander.newBuilder() to register your object and call .parse(argv).

Basic usage pattern:

1. Define a class with fields annotated with @Parameter.
2. Instantiate the class.
3. Use JCommander.newBuilder().addObject(yourObject).build().parse(args) to populate the fields.

import com.beust.jcommander.Parameter;
import com.beust.jcommander.JCommander;
import java.util.ArrayList;
import java.util.List;

public class Args {
  @Parameter
  private List<String> parameters = new ArrayList<>();

  @Parameter(names = { "-log", "-verbose" }, description = "Level of verbosity")
  private Integer verbose = 1;
}

// Usage
Args args = new Args();
String[] argv = { "-log", "2" };
JCommander.newBuilder()
  .addObject(args)
  .build()
  .parse(argv);

Add JCommander to your project using Maven or Gradle.

Maven

<dependency>
  <groupId>org.jcommander</groupId>
  <artifactId>jcommander</artifactId>
  <version>3.0</version>
</dependency>

Gradle

compile "org.jcommander:jcommander:3.0"

To prevent passwords from appearing in command line history, use the password = true attribute. This causes JCommander to prompt the user for the value in the console during execution.

By default, input is not echoed (hidden). You can enable echoing by setting echoInput = true.

@Parameter(names = "-password", description = "Connection password", password = true, echoInput = true)
private String password;

If you use a custom type frequently, implement IStringConverterFactory to map types to converters globally. This avoids repeating the converter attribute on every @Parameter annotation.

Register the factory using .addConverterFactory(factory) when building the JCommander instance.

public class Factory implements IStringConverterFactory {
  public Class<? extends IStringConverter<?>> getConverter(Class<T> forType) {
    if (forType.equals(HostPort.class)) return HostPortConverter.class;
    else return null;
  }
}

// Usage
JCommander jc = JCommander.newBuilder()
    .addObject(args)
    .addConverterFactory(new Factory())
    .build();

While you can set defaults by initializing fields, you can use IDefaultProvider for centralized or dynamic defaults.

JCommander provides built-in providers:

• PropertyFileDefaultProvider: Reads from jcommander.properties.
• EnvironmentVariableDefaultProvider: Reads from JCOMMANDER_OPTS.

You can chain providers using IDefaultProvider.sequenceOf(...).

private static final IDefaultProvider DEFAULT_PROVIDER = new IDefaultProvider() {
  @Override
  public String getDefaultValueFor(String optionName) {
    return "-debug".equals(optionName) ? "false" : "42";
  }
};

JCommander jc = JCommander.newBuilder()
    .addObject(new Args())
    .defaultProvider(DEFAULT_PROVIDER)
    .build();

Validation can be performed at two levels:

1. Individual Parameter Validation: Implement IParameterValidator to validate a single parameter's value. Use the validateWith attribute in @Parameter.
2. Global Parameter Validation: Implement IParametersValidator to validate the entire set of parsed parameters (e.g., checking for mutual exclusivity). Use the parametersValidators attribute in @Parameters.