Introduction

In Java, command line arguments arrive as the String[] args parameter of main. For very small programs, manual parsing is enough, but for real CLI tools you usually want a library that can handle options, defaults, validation, and help output cleanly.

Start with String[] args

Every argument is initially just a string in order.

1public class ShowArgs {
2    public static void main(String[] args) {
3        for (int i = 0; i < args.length; i++) {
4            System.out.println("arg[" + i + "] = " + args[i]);
5        }
6    }
7}

If you run:

java ShowArgs first second

then args[0] is first and args[1] is second.

This is enough for programs that only need positional parameters or one or two simple flags.

Manual parsing works for simple cases

For a small tool, you can scan the array yourself.

1public class ManualCli {
2    public static void main(String[] args) {
3        String input = null;
4        boolean verbose = false;
5
6        for (int i = 0; i < args.length; i++) {
7            switch (args[i]) {
8                case "--input":
9                    if (i + 1 >= args.length) {
10                        throw new IllegalArgumentException("--input requires a value");
11                    }
12                    input = args[++i];
13                    break;
14                case "--verbose":
15                    verbose = true;
16                    break;
17                default:
18                    throw new IllegalArgumentException("Unknown argument: " + args[i]);
19            }
20        }
21
22        System.out.println("input=" + input);
23        System.out.println("verbose=" + verbose);
24    }
25}

This is fine when the command line is small and fixed. Once options become numerous or interdependent, manual parsing becomes repetitive and error-prone.

Use a library for real CLI applications

Libraries such as picocli, Apache Commons CLI, and JCommander exist because robust CLI parsing has lots of edge cases. A parser library gives you:

• required and optional options
• help generation
• type conversion
• validation
• subcommands

picocli is a popular modern choice. A minimal example looks like this:

1import picocli.CommandLine;
2import picocli.CommandLine.Command;
3import picocli.CommandLine.Option;
4
5@Command(name = "app", mixinStandardHelpOptions = true)
6class App implements Runnable {
7
8    @Option(names = {"-i", "--input"}, required = true)
9    private String input;
10
11    @Option(names = "--verbose")
12    private boolean verbose;
13
14    public void run() {
15        System.out.println("input=" + input);
16        System.out.println("verbose=" + verbose);
17    }
18
19    public static void main(String[] args) {
20        int exitCode = new CommandLine(new App()).execute(args);
21        System.exit(exitCode);
22    }
23}

That is much easier to maintain than a growing manual switch statement once the CLI gets serious.

Decide between positional arguments and options

A good CLI usually separates:

• positional arguments for required ordered values
• named options for flags and optional values

For example, mytool input.txt output.txt is naturally positional. A verbosity switch or timeout value is better as --verbose or --timeout 10.

Good argument design matters as much as good parsing code. A confusing CLI remains confusing even if the parser library is excellent.

Common Pitfalls

• Treating all arguments as positional strings even when named options would make the CLI clearer.
• Writing manual parsing logic that does not validate missing option values or unknown flags.
• Forgetting that everything in args starts as a string and needs explicit conversion.
• Reimplementing help text and error formatting badly instead of using a parser library.
• Growing a simple manual parser far beyond the point where a CLI library would be easier to maintain.

Summary

• Java command line arguments arrive as String[] args in main.
• Manual parsing is fine for small simple tools.
• For real CLI applications, use a library such as picocli or Apache Commons CLI.
• Separate positional arguments from named options deliberately.
• The best parser choice depends on command complexity, not just personal preference.