Skip to content
Command Line Arguments and Options parser for the JVM
Find file
New pull request
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


A command line arguments parser for the JVM. Written in Java means it's fast, yet it'll work with any JVM language such as JRuby, Clojure, Scala, Mirah, etc...


Example Usage

Below is a simple example using all of the API methods for this library.

import mmargs.Arguments;
import java.util.List;
import java.util.Map;

public class Greetings
  public static void main(String[] args)
    Arguments spec = new Arguments();
    spec.addParameter("first-name", "The person's first name");
    spec.addOptionalParameter("title", "The person's title");
    spec.addMultiParameter("remaining-names", "The person's remaining names");
    spec.addSwitchOption("C", "caps", "Prints the name in all uppercase letters");
    spec.addValueOption("s", "salutation", "SALUTATION", "A salutation to be printed before the name");
    spec.addMultiOption("b", "body", "BODY", "Specifies parts of the message body");

    final Map<String,Object> options = spec.parse(args);

      usage(spec, (List) options.get("*errors"));
      String greeting = options.get("first-name").toString();
        greeting = options.get("title").toString() + " " + greeting;
        for(Object name : (List)options.get("remaining-names"))
          greeting += " " + name.toString();

        greeting = greeting.toUpperCase();

        greeting = options.get("salutation") + " " + greeting;

      System.out.println(greeting + ",");

        for(Object body : (List)options.get("body"))

  private static void usage(Arguments spec, List list)
    for(Object error : list)
    System.out.println("Usage: java Greetings " + spec.argString());

Creating the Spec

To specify required parameters, provide a name and description. If not provided an error is reported.

spec.addParameter("first-name", "The person's first name");

If a parameter is optional....

spec.addOptionalParameter("title", "The person's title");

Sometimes it's handy to have a catch all for parameters. A multi-parameter should be that last parameter added to the spec.

spec.addMultiParameter("remaining-names", "The person's remaining names");

Switch options result in a value of "on" if provided and null if not.

spec.addSwitchOption("C", "caps", "Prints the name in all uppercase letters");

Value options map to the provided value or null if none is provided.

spec.addValueOption("s", "salutation", "SALUTATION", "A salutation to be printed before the name");

Multi-options are collected into a List.

spec.addMultiOption("b", "body", "BODY", "Specifies parts of the message body");


When parse is called, all the arguments are parsed and a map of values it returned. All of the supplied params and options are strings keyed by their names. For multi-parameters, and multi-options, the key maps to a List of strings.

There are two special keys that you may find in the resulting map:

  1. *errors : In the event of errors during parsing, the *errors maps to a List of error strings.
  2. *leftover: Any extra parameters or unrecognized options will be collected in a List of strings.

Usage Message

Due to the many various way that a usage message could be printed, mmargs provides 3 methods to give you some flexibility.

  1. argString : describes the general structure of the command
  2. parametersString : describes each of the parameters
  3. optionsString : describes each of the options

Here's the out put of a parse error in our Greetings example:

Usage: java Greetings [options] <title> [first-name] [remaining-names*]
  title            The person's title
  first-name       The person's first name
  remaining-names  The person's remaining names

  -C, --caps                     Prints the name in all uppercase letters
  -s, --salutation=<SALUTATION>  A salutation to be printed before the name
  -b, --body=<BODY>              Specifies parts of the message body

Trying It Out

Minimal example

$ java -cp classes Greetings Yoda

No optional parameters and using the short names of:

$ java -cp classes Greetings Dave -C -s "I'm sorry" -b "I'm afraid I can't do that."
I'm sorry DAVE,
I'm afraid I can't do that.

Using two long names for options and taking advantage of multi option:

$ java -cp classes Greetings Bond Mr. --caps --salutation="No," --body="I expect you to die." --body="*evil grin*"
I expect you to die.
*evil grin* 

Using multi parameter

$ java -cp classes Greetings John Mr. Jacob Jingleheimer Schmidt --body "His name is my name too"
Mr. John Jacob Jingleheimer Schmidt,
His name is my name too
Something went wrong with that request. Please try again.