Programmatic API

String[] args = { "--verbose", "-f", "file1", "--file=file2", "-n1,2,3" };
ParseResult pr = commandLine.parseArgs(args);

List<String> originalArgs = pr.originalArgs(); // lists all command line args
assert Arrays.asList(args).equals(originalArgs);

assert pr.hasMatchedOption("--verbose"); // as specified on command line
assert pr.hasMatchedOption("-V");        // other aliases work also
assert pr.hasMatchedOption('V');         // single-character alias works too
assert pr.hasMatchedOption("verbose");   // and, command name without hyphens

ParseResult pr = commandLine.parseArgs("-f", "file1", "--file=file2", "-n1,2,3");

List<File> defaultValue = Collections.emptyList();
List<File> expected     = Arrays.asList(new File("file1"), new File("file2"));

assert expected.equals(pr.matchedOptionValue('f', defaultValue));
assert expected.equals(pr.matchedOptionValue("--file", defaultValue));

assert Arrays.equals(new int[]{1,2,3}, pr.matchedOptionValue('n', new int[0]));

ParseResult pr = commandLine.parseArgs("-f", "file1", "--file=file2", "-n1,2,3");

// Command line arguments after splitting but before type conversion
assert "1".equals(pr.matchedOption('n').stringValues().get(0));
assert "2".equals(pr.matchedOption('n').stringValues().get(1));
assert "3".equals(pr.matchedOption('n').stringValues().get(2));

// Command line arguments as found on the command line
assert "1,2,3".equals(pr.matchedOption("--num").originalStringValues().get(0));

class App {
    @Option(names = "-x") String x;
}
class Sub {
    @Parameters String[] all;
}
CommandLine cmd = new CommandLine(new App());
cmd.addSubcommand("sub", new Sub());
ParseResult parseResult = cmd.parseArgs("-x", "xval", "sub", "1", "2", "3");

assert parseResult.hasMatchedOption("-x");
assert "xval".equals(parseResult.matchedOptionValue("-x", "default"));

assert parseResult.hasSubcommand();
ParseResult subResult = parseResult.subcommand();

assert  subResult.hasMatchedPositional(0);
assert  subResult.hasMatchedPositional(1);
assert  subResult.hasMatchedPositional(2);
assert !subResult.hasMatchedPositional(3);

public static void main(String... args) {
    int exitCode = myParse(args);
    System.exit(exitCode);
}

int myParse(String... args) {
    CommandSpec spec = CommandSpec.create();
    // add options and positional parameters

    CommandLine cmd = new CommandLine(spec);
    try {
        ParseResult parseResult = cmd.parseArgs(args);

        // Did user request usage help (--help)?
        if (cmd.isUsageHelpRequested()) {
            cmd.usage(cmd.getOut());
            return cmd.getCommandSpec().exitCodeOnUsageHelp();

        // Did user request version help (--version)?
        } else if (cmd.isVersionHelpRequested()) {
            cmd.printVersionHelp(cmd.getOut());
            return cmd.getCommandSpec().exitCodeOnVersionHelp();
        }
        // invoke the business logic
        myBusinessLogic(parseResult);
        return cmd.getCommandSpec().exitCodeOnSuccess();

    // invalid user input: print error message and usage help
    } catch (ParameterException ex) {
        cmd.getErr().println(ex.getMessage());
        if (!UnmatchedArgumentException.printSuggestions(ex, cmd.getErr())) {
            ex.getCommandLine().usage(cmd.getErr());
        }
        return cmd.getCommandSpec().exitCodeOnInvalidInput();

    // exception occurred in business logic
    } catch (Exception ex) {
        ex.printStackTrace(cmd.getErr());
        return cmd.getCommandSpec().exitCodeOnExecutionException();
    }
}

void myBusinessLogic(ParseResult pr) throws java.io.IOException {
    int count = pr.matchedOptionValue('c', 1);
    List<File> files = pr.matchedPositionalValue(0, Collections.<File>emptyList());
    for (File f : files) {
        for (int i = 0; i < count; i++) {
            System.out.printf("%d: %s%n", i, f.getCanonicalFile());
        }
    }
}

public class MyApp {

    public static void main(String[] args) {
        CommandSpec spec = CommandSpec.create();
        spec.mixinStandardHelpOptions(true); // usageHelp and versionHelp options
        spec.addOption(OptionSpec.builder("-c", "--count")
                .paramLabel("COUNT")
                .type(int.class)
                .description("number of times to execute").build());
        spec.addPositional(PositionalParamSpec.builder()
                .paramLabel("FILES")
                .type(List.class).auxiliaryTypes(File.class) // List<File>
                .description("The files to process").build());
        CommandLine commandLine = new CommandLine(spec);

        // optionally configure streams and handlers to be used
        commandLine.setCaseInsensitiveEnumValuesAllowed(true) //configure a parser option
            .setOut(myOutWriter()) // configure an alternative to System.out
            .setErr(myErrWriter()) // configure an alternative to System.err
            .setColorScheme(myColorScheme()) // configure a custom color scheme
            .setExitCodeExceptionMapper(myMapper()) //  map exception to exit code
            .setParameterExceptionHandler(MyApp::invalidUserInput) // configure a custom handler
            .setExecutionExceptionHandler(MyApp::runtimeException) // configure a custom handler
        ;
        // set an execution strategy (the run(ParseResult) method) that will be called
        // by CommandLine.execute(args) when user input was valid
        commandLine.setExecutionStrategy(MyApp::run);
        int exitCode = commandLine.execute(args);
        System.exit(exitCode);
    }

    static int run(ParseResult pr) {
        // handle requests for help or version information
        Integer helpExitCode = CommandLine.executeHelpRequest(pr);
        if (helpExitCode != null) { return helpExitCode; }

        // implement the business logic
        int count = pr.matchedOptionValue('c', 1);
        List<File> files = pr.matchedPositionalValue(0, Collections.<File>emptyList());
        for (File f : files) {
            for (int i = 0; i < count; i++) {
                System.out.println(i + " " + f.getName());
            }
        }
        return files.size();
    }

    // custom handler for runtime errors that does not print a stack trace
    static int runtimeException(Exception e,
                                CommandLine commandLine,
                                ParseResult parseResult) {
        commandLine.getErr().println("INTERNAL ERROR: " + e.getMessage());
        return CommandLine.ExitCode.SOFTWARE;
    }

    // custom handler for invalid input that does not print usage help
    static int invalidUserInput(ParameterException e, String[] strings) {
        CommandLine commandLine = e.getCommandLine();
        commandLine.getErr().println("ERROR: " + e.getMessage());
        commandLine.getErr().println("Try '"
                + commandLine.getCommandSpec().qualifiedName()
                + " --help' for more information.");
        return CommandLine.ExitCode.USAGE;
    }
}