java-miniterm

miniterm is a Java library that provides low-level terminal access. Its main selling point is that it is extremely small (~25KB), making it ideal for CLI tools and applications where keeping dependencies lightweight matters.

Two variants are available:

• miniterm — legacy implementation, works with Java 8+
• miniterm-ffm — modern implementation using the Foreign Function & Memory API, requires Java 22+

Philosophy : these modules, and the project in general, have been expressly created to be as minimal as possible, it only offers the most essential functionality that is missing from Java to be able to use the features of a modern Terminal. Several other projects exist that do this as well, but they normally come with a whole bunch of other things that you might not need. miniterm on the other hand only does the work that you can't do with standard Java APIs. Everything else can be built on top.

And then we have utility modules (the "built on top"):

• ansiparser — compact ANSI escape sequence parser
• colors — terminal colour palette querying and setting
• mousetrack — terminal mouse-tracking helpers and event parser
• termcap — terminal capability detection

Acknowledgements : miniterm is inspired by and has unashamedly copied ideas and code from AEsh and Tamboui Panama backend.

Usage

import org.codejive.miniterm.Terminal;

public class Example {
    public static void main(String[] args) throws Exception {
        try (Terminal terminal = Terminal.create()) {
            // Do terminal stuff here...
        }
    }
}

Get terminal size

var size = terminal.size();
System.out.println("The size of the terminal is " + size);

Read key presses

terminal.enableRawMode();
while (true) {
    int key = terminal.read(1000);
    if (key == -1 || key == 3) { // Ctrl+C
        break; // End of stream
    } else if (key >= 0) {
        System.out.println("Key pressed: " + key);
    }
}

Read key presses & ANSI sequences

terminal.enableRawMode();
AnsiReader reader = new AnsiReader(() -> terminal.read(-1));
String seq;
while ((seq = reader.read()) != null) {
    if (seq.startsWith("\u001b")) {
        if (seq.equals("\u001b[A")) {
            System.out.println("Up arrow");
        } else { /* etc... */ }
    } else if (seq.charAt(0) == 3) {
        break; // Ctrl+C
    } else {
        System.out.println("Key pressed: " + seq);
    }
}

Handling mouse events

terminal.enableRawMode();
MouseTracking.enable(terminal, MouseTracking.Protocol.NORMAL);
MouseTracking.enableEncoding(terminal, MouseTracking.Encoding.SGR);
AnsiReader reader = new AnsiReader(() -> terminal.read(-1));
String seq;
while ((seq = reader.read()) != null) {
    if (MouseTracking.isMouseEvent(seq)) {
        MouseEvent ev = MouseTracking.parse(seq);
        System.out.printf("%-8s %-12s at (%d, %d)%n",
                ev.type(), ev.button(), ev.x(), ev.y());
    }
}

Detecting terminal capabilities

TermCaps caps = TermCaps.detect();
if (caps.colors() >= 256) {
    // render with rich colours
}

Query colors

Color bg = TermColors.queryBackground(terminal, () -> terminal.read(500));
if (bg != null) {
    // luminance check for dark/light theme detection
    boolean dark = (0.299 * bg.r8() + 0.587 * bg.g8() + 0.114 * bg.b8()) < 128;
}

Modules

Three artifacts are published independently:

Artifact	Description
miniterm	Legacy terminal implementation, Java 8+
miniterm-ffm	Modern FFM-based terminal implementation, Java 22+
ansiparser	Compact ANSI escape sequence parser, Java 8+
mousetrack	Terminal mouse-tracking helpers and event parser, Java 8+
termcap	Terminal capability detection, Java 8+
colors	Terminal colour palette querying and setting via OSC sequences, Java 8+

For dependency coordinates (Maven, Gradle, JBang) and module-specific usage details, see the individual module READMEs linked above.

Building

./mvnw clean install

Running examples

The examples/ folder contains several ready-to-run examples. Use the provided scripts to pick and run one interactively:

Linux/macOS:

# Using the legacy (Java 8+) implementation
./examples/run

# Using the FFM (Java 22+) implementation
./examples/run-ffm

Windows:

:: Using the legacy (Java 8+) implementation
examples\run.bat

:: Using the FFM (Java 22+) implementation
examples\run-ffm.bat

The scripts will list the available examples and let you choose one to run:

• PrintAnsi — prints the the ANSI sequence of each key pressed
• PrintCaps — prints the capabilities that the terminal supports
• PrintColors — detects and prints the colors that the terminal supports
• PrintKeys — prints the code of each key pressed
• PrintMouse — prints mouse events
• PrintSize — prints the current terminal dimensions
• WatchSize — watches and prints terminal size changes in real time