console-utils

A Java library for building styled console output. Provides boxes, colored text, separators, tables, progress bars, user input handling, and side-by-side layouts using ANSI escape codes.

Requires Java 21.

Getting Started

Step 1: Clone and install the library

Open a terminal and run:

git clone https://git.paulinis.net/raupy/console-utils.git
cd console-utils
./gradlew publishToMavenLocal

This builds the library and installs it into your local Maven repository (~/.m2/repository), so your other projects can find it as a dependency.

Step 2: Add the dependency to your project

Open your project's build file and add the dependency.

Gradle (Kotlin DSL) build.gradle.kts:

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    implementation("net.paulinis.raupy:console-utils:1.0")
}

Gradle (Groovy) build.gradle:

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    implementation 'net.paulinis.raupy:console-utils:1.0'
}

Maven pom.xml:

<dependency>
    <groupId>net.paulinis.raupy</groupId>
    <artifactId>console-utils</artifactId>
    <version>1.0</version>
</dependency>

For Maven you also need mavenLocal in your repositories:

<repositories>
    <repository>
        <id>local</id>
        <url>file://${user.home}/.m2/repository</url>
    </repository>
</repositories>

Step 3: Reload your project

In IntelliJ, click the Gradle reload button (or right-click pom.xml and select "Reload Project" for Maven). The library should now show up under "External Libraries".

Step 4: Use it

import net.paulinis.raupy.utils.ui.ConsoleUI;

public class Main {
    public static void main(String[] args) {
        ConsoleUI.successBox("Hello", "It works!");
    }
}

If you're running from Gradle and need user input, add this to your build.gradle.kts so System.in gets forwarded:

tasks.named<JavaExec>("run") {
    standardInput = System.`in`
}

Alternatively: JAR download

You can also download the JAR directly from the releases page and add it to your project's classpath manually.

Usage

All output methods are accessed through ConsoleUI. Input methods are on ConsoleInput.

Text output

import net.paulinis.raupy.utils.ui.ConsoleUI;
import net.paulinis.raupy.utils.ui.enums.AnsiColor;
import net.paulinis.raupy.utils.ui.enums.AnsiStyle;

ConsoleUI.pl("Hello World");
ConsoleUI.printlnColored("Green text", AnsiColor.GREEN);
ConsoleUI.printlnStyled("Bold text", AnsiStyle.BOLD);
ConsoleUI.printlnFormatted("Bold and red", AnsiColor.RED, AnsiStyle.BOLD);

Boxes

ConsoleUI.box("Simple box");
ConsoleUI.box("Title", "Box with a title");

ConsoleUI.infoBox("Information");
ConsoleUI.successBox("Done");
ConsoleUI.warningBox("Careful");
ConsoleUI.errorBox("Something went wrong");

ConsoleUI.fancyBox("Title", "Rounded heavy with bold");
ConsoleUI.headerBox("Title", "Centered with title on top");
ConsoleUI.menuBox("Menu", "1. Option A\n2. Option B");
ConsoleUI.cardBox("Card", "Rounded with colored title");
ConsoleUI.debugBox("Some debug output");
ConsoleUI.statusBox("Status", "Online", AnsiColor.GREEN);

Box Builder

For full control over appearance, use the builder:

import net.paulinis.raupy.utils.ui.enums.*;

ConsoleUI.boxBuilder()
    .title("Status")
    .content("All systems operational")
    .border(BorderType.DOUBLE)
    .color(AnsiColor.CYAN)
    .titleColor(AnsiColor.BRIGHT_CYAN)
    .width(40)
    .padding(2)
    .align(Align.CENTER)
    .draw();

Available border types: SINGLE, DOUBLE, ROUNDED, SINGLE_HEAVY, ROUNDED_HEAVY, ASCII, ASCII_DOTS, BLOCK, HASH, NONE.

Separators

ConsoleUI.separator(50);
ConsoleUI.separator(50, BorderType.DOUBLE);
ConsoleUI.separator(50, BorderType.SINGLE, AnsiColor.BLUE);

Tables

ConsoleUI.tableBuilder()
    .headers("Name", "Role", "Status")
    .row("Alice", "Admin", "Active")
    .row("Bob", "User", "Inactive")
    .border(BorderType.ROUNDED)
    .headerColor(AnsiColor.CYAN)
    .draw();

Per-column alignment:

ConsoleUI.tableBuilder()
    .headers("Item", "Price")
    .row("Coffee", "3.50")
    .row("Sandwich", "12.00")
    .columnAligns(Align.LEFT, Align.RIGHT)
    .draw();

Progress Bar

Simple inline progress bar:

for (int i = 0; i <= 100; i++) {
    ConsoleUI.progressBar(i, 100, 40);
    PlatformUtils.sleepMs(50);
}

buildProgressBar returns the bar as a string without printing it, which is useful for embedding in layouts or boxes.

Async Progress Tracking

ProgressTracker runs a background thread that renders the bar live while your task runs. It shows elapsed time and ETA automatically.

import net.paulinis.raupy.utils.ui.progress.ProgressTracker;

ProgressTracker tracker = ConsoleUI.progressTracker(100, 40)
    .label("Processing")
    .color(AnsiColor.GREEN)
    .statusColor(AnsiColor.BRIGHT_BLACK);

tracker.start();
for (int i = 0; i < 100; i++) {
    doWork(i);
    tracker.advance();
    tracker.status("item " + i);
}
tracker.finish("done");

Run a task async with automatic start/finish:

ConsoleUI.trackAsync(
    ConsoleUI.progressTracker(files.size(), 40).label("Upload"),
    tracker -> {
        for (int i = 0; i < files.size(); i++) {
            upload(files.get(i));
            tracker.update(i + 1, files.get(i).getName());
        }
    }
).join();

Track multiple tasks in parallel:

import net.paulinis.raupy.utils.ui.progress.MultiProgressTracker;

ProgressTracker t1 = ConsoleUI.progressTracker(100, 30).showEta(false);
ProgressTracker t2 = ConsoleUI.progressTracker(200, 30).showEta(false);

MultiProgressTracker multi = ConsoleUI.multiProgress().add(t1).add(t2);
multi.start();

// update t1 and t2 from separate threads
// ...

multi.awaitCompletion();

Layouts

Render multiple columns side by side:

ConsoleUI.layout()
    .add(ConsoleUI.boxBuilder().title("Left").content("Column 1"))
    .add(ConsoleUI.boxBuilder().title("Right").content("Column 2"))
    .spacing(4)
    .render();

Vertical alignment and separators between columns:

import net.paulinis.raupy.utils.ui.enums.VerticalAlign;

ConsoleUI.layout()
    .add(ConsoleUI.boxBuilder().title("A").content("Short"))
    .addSeparator(BorderType.SINGLE)
    .add(ConsoleUI.boxBuilder().title("B").content("Longer\ncontent\nhere"))
    .verticalAlign(VerticalAlign.MIDDLE)
    .render();

User Input

import net.paulinis.raupy.utils.input.ConsoleInput;

String name = ConsoleInput.readLine("Enter your name");
String required = ConsoleInput.readNotEmptyLine("This field is required");
int number = ConsoleInput.readInt("Pick a number");
int bounded = ConsoleInput.readIntInRange("Pick 1 to 10", 1, 10);
double price = ConsoleInput.readDouble("Enter price");
boolean confirm = ConsoleInput.readYesNo("Are you sure?");
ConsoleInput.waitForEnter("Press Enter to continue");

Menu selection from a list of options:

List<String> options = List.of("Save", "Load", "Quit");
String choice = ConsoleInput.readChoice("Pick an action", options);

Platform Detection

import net.paulinis.raupy.utils.system.PlatformUtils;

if (PlatformUtils.isLinux()) {
    // linux-specific logic
}

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.