If a command has multiple subcommands, and if the parse method threw a ParameterException, it is not possible to find out which subcommand threw the exception. This means it is not possible to give specific usage help feedback to the user on how the subcommand should be used correctly.

Solution: add method ParameterException::getCommandLine that returns the (sub)command that threw the exception. Client code could look like this:

CommandLine top = new CommandLine(new MyApp());
try {
    List<CommandLine> parsedCommands = top.parse(args);
    // ... do something with the parsed commands
} catch (ParameterException ex) { // incorrect user input for one of the subcommands
    out.println(ex.getMessage());
    ex.getCommandLine().usage(out); // get the offended subcommand from the exception
}

To implement this, change the ParameterException constructor (and similar for all subclasses) to add a required CommandLine parameter.

Note to self: the ParameterException hierarchy needs to be refactored. Exceptions thrown from the CommandLine constructor should not extend from ParameterException. Let's introduce a new ConfigurationException (extends RuntimeException) to indicate a CommandLine could not be constructed. DuplicateOptionAnnotationException and ParameterIndexGapException should extend this new exception. CommandLine constructor code throwing IllegalArgumentException and IllegalStateException should throw a ConfigurationException instead.

The remaining exceptions can extend ParameterException, and CommandLine can be a mandatory ParameterException constructor parameter.

These are breaking API changes, so require a major version increment.