Close

Quick CLI

What is Quick CLI?

Quick CLI is the quickest way to create command line program in Java. It is an open source annotation based framework for creating shell program. It enables application developers to build command line tools without writing down boilerplate code. It's very simple and easy to learn.

Here are the quick features:
  1. It supports Linux style arguments and options.
  2. It's annotation based. You just have to use four annotations on method level.
  3. It generates help text, based on user provided descriptions on annotations
  4. By default, it appends 'help' and 'exit' commands.
  5. Prints information in table/column format with flexible alignments and wrapping.
  6. Automatic type conversion depending on the method parameter type

Supported Syntax

    CommandName [Options]...   [Option-Flags]...   [Arguments]...
where
  1. Options are key value pairs e.g. --opt1=theOptValue
  2. Options-Flags are boolean flags e.g. -f -t -c etc. They can be combined together as -ftc
  3. Arguments are input to the command e.g. consider linux command ls -l folderName, here fileName is the argument to the ls command

Hello World Example

  1. Step 1: Create a maven project either from your IDE or by using archetype like maven-archetype-quickstart and add the Quick CLI dependency:
    <dependency>
        <groupId>com.logicbig.cli</groupId>
        <artifactId>quick-cli</artifactId>
        <version>1.0</version>
    </dependency>
    Step 2 : Create method which will define the command and will get called on executing the command
    public class CommandHandler {
        @Command(name = "sayHi", desc = "Test command")
        public void sayHiCommand(@Argument(name = "userName", desc = "user name",
                mandatory = true) String user) {
            System.out.println("Hi there! " + user);
        }
    }
  2. Step 3: Scan class and start your shell.
    public static void main(String... strings) {
        QuickCLIShell cli = new QuickCLIShell("Hello World", "An example shell prgoram");
        cli.scanCommands(CommandHandler.class);
        cli.start();
    }
That's it. Now run your main method from command line.
    ---------------------------------------------------------------------------
    Hello World
    An example shell prgoram
    ---------------------------------------------------------------------------
    Valid Commands: [sayHi, help, exit]
    Please use 'help' command to view details
    Hello World>_

Run your command 'sayHi'
Hello World>sayHi Mike
Hi there! Mike
Hello World>_

Run 'help' command
    Hello World>help
  ---------------------------------------------------------------------------
  sayHi  Description  Test command
               Usage  sayHi <userName>
           Argument:
            userName  user name(Mandatory)

   help  Description  prints help
               Usage  help [<command>]
           Argument:
             command  The command name

   exit  Description  terminates shell
               Usage  exit

  ---------------------------------------------------------------------------
  Please use double quotes for argument and option values if they contain non alphabetical characters
  Option Flags can be combined together e.g. -a -b -c can be combined as -abc
  Options must start with double hyphen e.g. --details=value
Run 'exit' command to terminate the shell.

Quick CLI Annotations

Let's consider following linux ls command as example

ls --color=auto -v myDir

The corresponding annotations usage and the method declaration:

@Command(name = "ls", desc = "List information about the FILEs")
public void listCommand(
     @Option(name = "color", desc = "colorize the output") String color,
     @OptionFlag(name = 'v', desc = "natural sort of (version) numbers within text") boolean vFlag,
     @Argument(name = "dirName", desc = "The directory, by default current directoy") String dir) {

    //apply list logic here 
    }

We are not going to implement the logic for above command. We just set up the annotations. All annotations that we need to use for Quick CLI, are defined in package com.logicbig.cli.annotation

Here's the break down of Quick CLI annotations we have used above.

Command Part Quick CLI Annotation explanation
ls Command Command should be annotated on method level. In this example the name parameter should be: name="ls" along with suitable desc
--color=auto Option Option should be annotated on method parameter. In this case the type of the parameter should be String. Quick CLI supports java.lang.String, Sub types of java.lang.Number (except for Atomic ones) and java.lang.Boolean. Corresponding primitives also work.
-v OptionFlag OptionFlag should be annotated on method parameter level. The type of the parameter has to be Boolean/boolean
myDir Argument Argument should also be annotated on method parameter level. The type could be any supported type as described above. As command arguments are not associated with names (from user perspective), the values entered by user are assigned in the order they are defined on the method. Mandatory arguments are always assigned first.


Command Method return Type

The command method can return command result as String. User can define the return type as void as well. In that case user is responsible to output the result himself/herself. User should use ConsoleWriter for that purpose. The instance of ConsoleWriter can be retrieved via static method: QuickCLIShell#getWriter()

Please check out an example project here

Quick CLI Releases

The latest version is 1.0
Download Now

Documentation

Javadoc (Quick CLI 1.0)
Source

Quick CLI License

Apache License 2.0

Minimum Requirements

JDK 1.8