Need help with clamshell-cli?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

128 Stars 38 Forks Apache License 2.0 58 Commits 13 Opened issues


A framework to build command-line console applications in Java

Services available


Need anything else?

Contributors list

# 55,719
The Jul...
48 commits

Build Status


Clamshell-Cli is a framework for building console-based command-line applications in Java. Clamshell uses a simple plugin architecture (based on the [ ServiceLoader API]) that let developers deploy components to build components with control over all aspects of console-based applications including splashscreen display, IO, prompt, input control, and command delegation. Clamshell-Cli comes with a default runtime that implements all of the basic components needed for a fully functioning console-based app. To customize the runtime with your own command, you simply create and deploy your own plugin jars (see example below).


  • Version 0.5.2 released. It is a bug fix to update jline 1.0 to support Windows 64-bit. [ Download here.]


  • Easy to get started
  • Small API footprint with low learning curve
  • Ability to build complex CLI tools such as REPL using plugin architecture
  • Simple component model that imposes little constraints on your design
  • The plugin architecture is designed for extensibility and feature-scalability:
    • If you don't like how the default implementation works, you can change it completely
    • Implement the components you want to change and your feature will be included next time the console is restarted
  • Statically-defined extension points provide control over all facets of console-based apps including:
    • A Splashscreen
    • Console IO
    • Prompt
    • Input Controller
    • Command Handlers
  • Each extension point is mapped to a Java type for easy implementation
  • Plugins are deployed as simple jar files
  • Support for input hints (tab-press at the console)
  • Support for input buffer history

Getting Started

It's easy to get started with Clamshell-Cli to build your first console application. * First, download the packaged zipped binary distribution from this site. This is a default runtime implementation that you can use for your own CLI tools. * Unzip at a location of your choice. The zip file will create a directory named

(will refer to it as {CLIHOME}). * Change directory inside {CLIHOME} and inspect the files. You will see the followings:
[email protected] 1 299   Mar  17 cli.config
[email protected] 1 3748  Mar  18 cli.jar
drwxrwxrwx  5 170   Mar  18 clilib
drwxrwxrwx  4 136   Mar  18 lib
drwxrwxrwx  5 170   Mar  18 plugins
- Clamshell-Cli configuration file *
- the launcher jar file *
- lib files to boot Clamshell-Cli *
- place your dependency jars here *
- location for Clamshell-Cli plugin jars

From within {CLI_HOME}, start the Clamshell-Cli launcher by typing:

> java -jar cli.jar
 .d8888b.  888                         .d8888b.  888               888 888
d88P  Y88b 888                        d88P  Y88b 888               888 888
888    888 888                        Y88b.      888               888 888
888        888  8888b.  88888b.d88b.   :Y888b.   88888b.   .d88b.  888 888
888        888     :88b 888 :888 :88b     :Y88b. 888 :88b d8P  Y8b 888 888
888    888 888 .d888888 888  888  888       :888 888  888 88888888 888 888
Y88b  d88P 888 888  888 888  888  888 Y88b  d88P 888  888 Y8b.     888 888
 :Y8888P:  888 :Y888888 888  888  888  :Y8888P:  888  888  :Y8888  888 888

                                              Command-Line Interpreter

Java version: 1.6.0_22 Java Home: /usr/lib/jvm/java-6-openjdk/jre OS: Linux, Version: 2.6.38-10-generic

prompt> _

Rightaway, you see three plugins in action: * Splashscreen Plugin - displays the ASCII text art scree * The Prompt - displays the current prompt at the command-line * The IOConsole - accepts user input at the command-line

The default runtime does not do too much. It does, however, provide a command/controller implementation. An internal

Input Controller
(a plugin) parses input from the command-line, then delegates handling of the input to a registered
plugin (if any).

If you type 'help' at the prompt, for instance, you will be actually invoking the

plugin which lists help info for all Command objects that are mapped. Each command is backed by a plugin class installed in the
prompt> help

Available Commands

  exit       Exits ClamShell.
  help       Displays help information for available commands.

sysinfo Displays current JVM runtime information. time Prints current date/time

prompt> _

Adding A Command

As stated above, Clamshell-Cli uses a plugin architecture. All extension points of the framework can be customized by providing your own plugins. This section shows how to add a new Command plugin and deploy it. It examines the implementation of the

command using the
plugin (deployed with the runtime).

Here are the simple steps for creating your own Command: * Create a new Java project (standard or maven) in your favorite IDE with a class that extends interface

interface (see below). * Package your project as a ServiceLoader SPI jar file (say,
) and drop it in directory
* Voila! You just added your first command to Clamshell-Cli

The Code

public class TimeCmd implements Command {
    private static final String NAMESPACE = "syscmd";
    private static final String ACTION_NAME = "time";

public Object execute(Context ctx) {
    IOConsole console = ctx.getIoConsole();
    console.writeOutput(String.format("%n%s%n%n",new Date().toString()));
    return null;

public void plug(Context plug) {
    // no load-time setup needed

public Command.Descriptor getDescriptor(){
    return new Command.Descriptor() {
        @Override public String getNamespace() {return NAMESPACE;}

        public String getName() {
            return ACTION_NAME;

        public String getDescription() {
           return "Prints current date/time";

        public String getUsage() {
            return "Type 'time'";

        public Map<string string> getArguments() {
            return Collections.emptyMap();


A quick explanation of the code is in order: * Method

- invoked by the input controller instance when it detects the String
from the command-line. The method retrieves the IOConsole from the context object and use it to print the time. It returns null to the controller (indicating the command did not generate a result). * Method
- a lifecycle method that is invoked by the framework when the command is first initialized. For our example, there nothing to do. * Method
- returns an instance of interface
which is used to describe the features and document the Command. For our example, the Descriptor interface is implemented anonymously with the following methods: * Method
- returns a string identifying the command's namespace. This value can be used by input controllers to avoid command name collisions. * Method
- returns the string mapped to this command object. In our implementation, it returns "time". * Method
- intended to provide a descriptive way of using the command. * Method
- returns a Map containing the description for each arguments that may be attached to the command. This example uses none.

Package Your Plugin

Once your class compiles properly, package the project as a standard Java Service provider (SPI). To do this, do the followings: * In your source tree, create service descriptor text file META-INF/services/org.clamshellcli.api.Plugin * On the first line of that file, put

(assuming the class is placed in package
). * Next, save the text file and package the project as a jar file (it is important that the descriptor text file gets copied into your jar)

Find more information on Java's Service Loader API: * [ Service Loader API] * [ Article on Java Extensibility]

Update File cli.config

Before your command can be made available in the console, you must let Clamshell-cli know about it. cli.config is JSON-formatted configuration file where you declare and configure your input controller components. In order for your controller to respond to your command, you must configure the controller properly to respond to the input pattern corresponding to your command.

The sample code below shows the configuration of the Command Controller (default controller that comes with Clamshell-Cli):


Deploy and Test the Command

  • Drop the jar file in the
    directory (shown above).
  • Start the Clamshell-Cli runtime.
  • From the command-line type 'help' and you should see your new command listed.

Developing with the API

When creating your own console-based tool, you can integrate the Clamshell-Cli API by directly pointing to the jar files or use Maven.

Direct Setup

From within your Java IDE, add the followings to your classpath * {CLIHOME}/clilib/clamshell-api-{version}.jar
* {CLI

Maven Artifacts

  • Repository:
        Clamshell-Cli Repository
  • POM dependencies:

Clamshell-Cli Examples

The best way to learn how to use the Clamshell-Cli API is to download the source code and look at how the Command plugins are implemented. You can also check out: * Jmx-Cli, a fully-functional JMX command-line tool implemented using the Clamshell-Cli API []

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.