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.

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]...

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();
   }

    ---------------------------------------------------------------------------
    Hello World
    An example shell prgoram
    ---------------------------------------------------------------------------
    Valid Commands: [sayHi, help, exit]
    Please use 'help' command to view details
    Hello World>_

Hello World>sayHi Mike
Hi there! Mike
Hello World>_

    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

Quick CLI Annotations

Let's consider following linux ls command as example

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 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