Parsing Command-Line Parameters with Airline

1. Introduction

In this tutorial, we'll introduce Airline — an annotation-driven Java library for building Command-Line Interfaces (CLIs).

2. Scenario

When building a command-line application, it's natural to create a simple interface to allow the user to mold the output as needed. Almost everyone has played with Git CLI and can relate to how powerful, yet simple, it is. Alas, few tools come in handy when building such an interface.

Airline aims to reduce the boilerplate code typically associated with CLIs in Java, as most common behaviors can be achieved with annotations and zero user code.

We're going to implement a small Java program that will exploit Airline's functionalities to mimic a common CLI. It'll expose user commands for setting up our program configuration, like defining the database URL, credentials, and logger verbosity. We'll also dive under the surface of our library and use more than its basics to probe if it can handle some complexity.

3. Setup

To get started, let's add the Airline dependency to our pom.xml:

<dependency>
    <groupId>com.github.rvesse</groupId>
    <artifactId>airline</artifactId>
    <version>2.7.2</version>
</dependency>

4. A Simple CLI

Let's create our entry point for the application — the CommandLine class:

@Cli(name = "baeldung-cli",
  description = "Baeldung Airline Tutorial",
  defaultCommand = Help.class)
public class CommandLine {
    public static void main(String[] args) {
        Cli<Runnable> cli = new Cli<>(CommandLine.class);
        Runnable cmd = cli.parse(args);
        cmd.run();
    }
}

Through a simple @Cli annotation, we have defined the default command that will run on our application – the Help command.

The Help class comes as part of the Airline library and exposes a default help command using -h or –help options.

Just like that, the basic setup is done.

5. Our First Command

Let's implement our first command, a simple LoggingCommand class that will control the verbosity of our logs. We'll annotate the class with @Command to ensure that the correct command is applied when the user calls setup-log:

@Command(name = "setup-log", description = "Setup our log")
public class LoggingCommand implements Runnable {

    @Inject
    private HelpOption<LoggingCommand> help;
	
    @Option(name = { "-v", "--verbose" }, 
      description = "Set log verbosity on/off")
    private boolean verbose = false;

    @Override
    public void run() {
        if (!help.showHelpIfRequested())
            System.out.println("Verbosity: " + verbose);
        }
    }
}

Let's take a closer look at our example command.

First, we've set a description so that our helper, thanks to the injection, will display our command options when requested.

Then we declared a boolean variable, verbose, and annotated it with @Option to give it a name, description, and also an alias -v/–verbose to represent our command-line option to control verbosity.

Finally, inside the run method, we instructed our command to halt whenever the user asks for help.

So far, so good. Now, we need to add our new command to the main interface by modifying the @Cli annotation:

@Cli(name = "baeldung-cli",
description = "Baeldung Airline Tutorial",
defaultCommand = Help.class,
commands = { LoggingCommand.class, Help.class })
public class CommandLine {
    public static void main(String[] args) {
        Cli<Runnable> cli = new Cli<>(CommandLine.class);
        Runnable cmd = cli.parse(args);
        cmd.run();
    }
}

Now, if we pass setup-log -v to our program, it will run our logic.

6. Constraints and More

We have seen how Airline generates CLI flawlessly, but… there's more!

We can specify constraints (or restrictions) for our parameters to handle allowed values, requirements or dependencies, and more.

We're going to create a DatabaseSetupCommand class, which will respond to the setup-db command; same as we did earlier, but we'll add some spice.

First, we'll request the type of database, accepting only 3 valid values through @AllowedRawValues:

@AllowedRawValues(allowedValues = { "mysql", "postgresql", "mongodb" })
@Option(type = OptionType.COMMAND,
  name = {"-d", "--database"},
  description = "Type of RDBMS.",
  title = "RDBMS type: mysql|postgresql|mongodb")
protected String rdbmsMode;

When using a database connection, without any doubt, users should supply an endpoint and some credentials to access it. We'll let CLI handle this through one (URL mode) or more parameters (host mode). For this, we'll use the @MutuallyExclusiveWith annotation, marking each parameter with the same tag:

@Option(type = OptionType.COMMAND,
  name = {"--rdbms:url", "--url"},
  description = "URL to use for connection to RDBMS.",
  title = "RDBMS URL")
@MutuallyExclusiveWith(tag="mode")
@Pattern(pattern="^(http://.*):(d*)(.*)u=(.*)&p=(.*)")
protected String rdbmsUrl = "";
	
@Option(type = OptionType.COMMAND,
  name = {"--rdbms:host", "--host"},
  description = "Host to use for connection to RDBMS.",
  title = "RDBMS host")
@MutuallyExclusiveWith(tag="mode")
protected String rdbmsHost = "";

Note that we used the @Pattern decorator, which helps us define the URL string format.

If we look at the project documentation, we'll find other valuable tools for handling requirements, occurrences, allowed values, specific cases, and more, enabling us to define our custom rules.

Finally, if the user selected the host mode, we should ask them to provide their credentials. In this way, one option is dependent on another. We can achieve this behavior with the @RequiredOnlyIf annotation:

@RequiredOnlyIf(names={"--rdbms:host", "--host"})
@Option(type = OptionType.COMMAND,
  name = {"--rdbms:user", "-u", "--user"},
  description = "User for login to RDBMS.",
  title = "RDBMS user")
protected String rdbmsUser;

@RequiredOnlyIf(names={"--rdbms:host", "--host"})
@Option(type = OptionType.COMMAND,
  name = {"--rdbms:password", "--password"},
  description = "Password for login to RDBMS.",
  title = "RDBMS password")
protected String rdbmsPassword;

What if we need to use some drivers to handle the DB connection? And also, suppose we need to receive more than one value in a single parameter. We can just change the option type to OptionType.ARGUMENTS or – even better – accept a list of values:

@Option(type = OptionType.COMMAND,
  name = {"--driver", "--jars"},
  description = "List of drivers",
  title = "--driver <PATH_TO_YOUR_JAR> --driver <PATH_TO_YOUR_JAR>")
protected List<String> jars = new ArrayList<>();

Now, let's not forget to add the database setup command to our main class. Otherwise, it won't be available on CLI.

7. Run

We did it! We finished our project, and now we can run it.

As expected, without passing any parameters, Help is invoked:

$ baeldung-cli

usage: baeldung-cli <command> [ <args> ]

Commands are:
    help        Display help information
    setup-db    Setup our database
    setup-log   Setup our log

See 'baeldung-cli help <command>' for more information on a specific command.

If we instead execute setup-log –help, we get:

$ baeldung-cli setup-log --help

NAME
        baeldung-cli setup-log - Setup our log

SYNOPSIS
        baeldung-cli setup-log [ {-h | --help} ] [ {-v | --verbose} ]

OPTIONS
        -h, --help
            Display help information

        -v, --verbose
            Set log verbosity on/off

Finally, supplying parameters to these commands will run the correct business logic.

8. Conclusion

In this article, we have built a simple yet powerful command-line interface with very little coding.

The Airline library, with its powerful functionalities, simplifies the CLI, providing us a general, clean and reusable infrastructure. It allows us, developers, to concentrate on our business logic rather than spending time designing what should be trivial.

As always, the code can be found over on GitHub.