Airline is a Java library providing an annotation-based framework for parsing command line interfaces.
It supports both simple single commands through to complex git style interfaces with groups and sub-groups.
Additionally it provides many powerful features including, but not limited to, the following:
Our project website at http://rvesse.github.io/airline/ contains a fairly comprehensive user guide. Some portions are still under development but it covers the vast majority of the features of the library.
To use airline you need to add a dependency to it to your own code, the Maven artifacts are described later in this ReadMe.
You then need to use the various annotations to annotate your command classes:
@Command
is used to annotate classes@Option
is used to annotate fields to indicate they are options@Arguments
is used to annotate fields that take in arguments@AirlineModule
can be used to modularise option
definitions into separate classesPlease see the examples module for a range of examples that show off the many features of this library and practical examples of using the annotations.
Or for a quick tutorial why not read our Introduction to Airline in our User Guide.
Simply create a parser instance via SingleCommand.singleCommand()
passing in a class that is annotated with the
@Command
annotation e.g.
public static void main(String[] args) {
SingleCommand<YourClass> parser = SingleCommand.singleCommand(YourClass.class);
YourClass cmd = parser.parse(args);
// Execute your command however is appropriate e.g.
cmd.run();
}
Create an instance of a Cli
, this can be done either using the CliBuilder
or by annotating a class with the @Cli
annotation. This is somewhat more involved so please see the
User Guide or the examples module for proper
examples.
Note that typically you will want to create an executable JAR for your CLI using something like the Maven Shade plugin.
This will then allow you to create a simple wrapper script that invokes your CLI.
#!/bin/bash
# myapp
java -jar my-app.jar "$@"
Note: You must use "$@"
here as otherwise Bash may expand/interpret arguments and as a result the JVM may not
receive the expected arguments that the user enters.
If this is done you can then invoke your application e.g.
myapp --global-option command --command-option arguments
Or:
myapp --global-option group --group-option command --command-option arguments
Airline is licensed under the Apache Software License Version 2.0, see provided LICENSE
See provided NOTICE for Copyright Holders
As of 3.0.0
Airline requires Java 11, see [guide/practise/jdk.md] for more details.
This library is available from Maven Central with the latest stable release being 3.0.0
Use the following maven dependency declaration:
<dependency>
<groupId>com.github.rvesse</groupId>
<artifactId>airline</artifactId>
<version>3.0.0</version>
</dependency>
Snapshot artifacts of the latest source are also available using the version 3.0.1-SNAPSHOT
from the
OSSRH repositories.
CI builds are run on Travis CI , see
build information and history at https://travis-ci.org/rvesse/airline
This is a substantially rewritten fork of the original airline library created based on improvements predominantly developed by myself plus some minor improvements taken from the Clark & Parsia fork. It has significantly deviated from the original library and gained many powerful features that differentiate it from both the original and other libraries with similar goals.
Airline 2 contains significant breaking changes from Airline 1.x, please see Migrating.md for more details on how to migrate code forward.
Airline 2.1 contains some further minor breaking changes that should only affect advanced users, again please see Migrating.md for more details on how to migrate code forward. Some users may need to add additional Maven dependencies if they were using help formats other than the basic CLI help.
Airline 2.2 has some minor breaking changes that may affect users of the @Arguments
annotation, again please see
Migrating.md for more details.
Airline 2.9 has some changes to composition in preparation for future breaking changes, most notably introducing the
@AirlineModule
annotation as a replacement for @Inject
. It remains backwards compatible with prior 2.x releases
but users may wish to start making changes to ease future transitions.
Airline 3.0.0 has several major breaking changes, this includes updating the minimum JDK version to 11, making some dependencies optional and much improved JPMS compatibility.