CliParseWizard

Lightweight Java framework for building command-line applications

v1.0.0

Overview

CliParseWizard is a lightweight Java library for creating command-line applications. It lets developers define commands with different argument types, parse user input, validate arguments, execute business logic and provide helpful error messages and usage hints.

Declarative commands

Define commands with arguments and attach executable logic via a simple builder API.

Multiple argument types

Supports flags, positional, key-value and multiple-value arguments.

Validation & Help

Built-in validation of required arguments and error/hint generation.

Small & modular

Minimal footprint and modular structure — easy to extend for custom types.

Quick Start

Register commands with CLIProcessor, define arguments and call process(args) to parse and dispatch.


CLIProcessor processor = new CLIProcessor();

Command greet = processor.getCommandBuilder()
    .setCommandName("greet")
    .addArgument(new PositionalArgument("name", true, null))
    .addArgument(new FlagArgument("verbose", false, null))
    .setExecutable(result -> {
        String name = (String) result.getParsedArguments().get("name");
        boolean verbose = result.getParsedArguments().get("verbose") != null;
        System.out.println(verbose ? "Hello, " + name + " (verbose)" : "Hello, " + name);
    })
    .build();

String[] argv = new String[] {"greet", "Alice", "--verbose"};
ParsingResult res = processor.process(argv);

API Highlights

CLIParser

Parses raw argv into a ParsingResult and performs validation.

Command / CommandBuilder

Define commands, their arguments and attach an Executable callback.

Argument

Abstract base type for argument implementations: FlagArgument, PositionalArgument, KeyValueArgument, MultipleValuesArgument.

CommandsRegistry / CLIProcessor

Registry for commands and high-level processor that runs parsing and dispatch.

Examples

1. Defining a simple command


CLIProcessor processor = new CLIProcessor();

Command command = processor.getCommandBuilder()
    .setCommandName("greet")
    .setExecutable(parsingResult -> {
        String name = (String) parsingResult.getParsedArguments().get("name");
        System.out.println("Hello, " + name + "!");
    })
    .addArgument(new PositionalArgument("name", true, null))
    .build();

processor.addCommand(command);

2. Command with flags


Command flagCommand = processor.getCommandBuilder()
    .setCommandName("run")
    .setExecutable(result -> {
        boolean verbose = result.getParsedArguments().get("verbose") != null;
        System.out.println("Verbose mode: " + verbose);
    })
    .addArgument(new FlagArgument("verbose", false, null))
    .build();

processor.addCommand(flagCommand);

3. Key-value argument


Command keyValueCommand = processor.getCommandBuilder()
    .setCommandName("config")
    .setExecutable(result -> {
        String host = (String) result.getParsedArguments().get("host");
        System.out.println("Server host: " + host);
    })
    .addArgument(new KeyValueArgument("host", true, "localhost"))
    .build();

processor.addCommand(keyValueCommand);

4. Multiple values


Command multiValueCommand = processor.getCommandBuilder()
    .setCommandName("add-tags")
    .setExecutable(result -> {
        java.util.List tags = (java.util.List) result.getParsedArguments().get("tags");
        System.out.println("Tags: " + String.join(", ", tags));
    })
    .addArgument(new MultipleValuesArgument("tags", true, null))
    .build();

processor.addCommand(multiValueCommand);

5. Handling missing/invalid arguments

The parser validates required arguments and collects errors in ParsingResult. On failure the CLIProcessor prints errors and usage hints.

Installation

Add CliParseWizard to your Maven project:

<dependency>
    <groupId>com.siperf</groupId>
    <artifactId>cliparsewizard</artifactId>
    <version>1.0.0</version>
</dependency>

Changelog

1.0.0 — 2026-04-22