terminal-ui/docs/Examples.md

Examples

All examples use import dev.jakub.terminal.Terminal; and import dev.jakub.terminal.core.Color; where needed. Use System.out or omit the argument where .print() has a no-arg overload.

---

Text & rules

Terminal.print("Hello").color(Color.CYAN).bold().println();

Terminal.rule().character('=').print();
Terminal.rule().doubles().prefix("-- ").suffix(" --").print();

Key-value & box

Terminal.keyValue()
    .row("Name", "terminal-ui")
    .row("Version", "1.0")
    .separator(" = ")
    .print(System.out);

Terminal.box()
    .title("Info")
    .line("First line")
    .lines("Second", "Third")
    .print(System.out);

Table

Terminal.table()
    .header("Col A", "Col B", "Col C")
    .row("1", "2", "3")
    .row("4", "5", "6")
    .print(System.out);

// From a list of rows (e.g. from CSV or DB)
List<String[]> rows = List.of(
    new String[]{"Alice", "10"},
    new String[]{"Bob", "20"}
);
Terminal.table()
    .header("Name", "Score")
    .rows(rows)
    .print(System.out);

// One-liner with header + data
Terminal.table()
    .fromRows(new String[]{"A", "B"}, List.of(new String[]{"1", "2"}, new String[]{"3", "4"}))
    .print(System.out);

Tree

Terminal.tree()
    .node("root")
        .child("src")
            .child("main").end()
            .child("test").end()
        .end()
        .child("docs")
    .end()
    .print(System.out);

Columns

Terminal.columns()
    .column("Left\ncolumn\ntext")
    .column("Middle")
    .column("Right")
    .print(System.out);

Steps (wizard-style)

Terminal.steps()
    .step("Setup", Steps.Status.DONE)
    .step("Build", Steps.Status.RUNNING)
    .step("Deploy", Steps.Status.PENDING)
    .print(System.out);

(Use import dev.jakub.terminal.components.Steps; for Steps.Status.)

Breadcrumb

Terminal.breadcrumb()
    .crumb("Home")
    .crumb("Projects")
    .crumb("terminal-ui")
    .separator(" / ")
    .print(System.out);

Interactive: Prompt

String name = Terminal.prompt("Name: ").ask();
String secret = Terminal.prompt("Password: ").masked().ask();
// With shared scanner (e.g. in a loop):
String line = Terminal.prompt("Input: ").ask(sharedScanner);

// With validation (asks again until input matches):
String age = Terminal.prompt("Age: ").validate(s -> s.matches("\\d+")).ask();
String email = Terminal.prompt("Email: ")
    .validate(s -> s.contains("@"))
    .retryMessage("Invalid email, try again: ")
    .ask();

Interactive: Confirm

boolean yes = Terminal.confirm("Continue?").defaultYes().ask();
boolean no = Terminal.confirm("Delete?").defaultNo().ask();
boolean answer = Terminal.confirm("Proceed?").ask(sharedScanner);

Interactive: Menu

String env = Terminal.menu()
    .title("Choose environment")
    .option("Development")
    .option("Staging")
    .option("Production")
    .select();

Interactive: SelectList (arrows + Enter)

String choice = Terminal.selectList()
    .title("Pick one")
    .option("Option A")
    .option("Option B")
    .option("Option C")
    .select();

Interactive: Pager

Terminal.pager()
    .lines("Line 1", "Line 2", "Line 3", "Line 4", "Line 5")
    .pageSize(3)
    .interactive();

Progress bar

ProgressBar bar = Terminal.progressBar()
    .total(100)
    .width(40)
    .style(ProgressBar.Style.BLOCK)
    .build();
for (int i = 0; i <= 100; i++) {
    bar.update(i);
    Thread.sleep(30);
}

(Use import dev.jakub.terminal.live.ProgressBar;.)

Spinner

Spinner spin = Terminal.spinner().message("Loading...").start();
// ... do work ...
spin.stop();

(Use import dev.jakub.terminal.live.Spinner;.)

Diff

Terminal.diff()
    .before("old line 1\nold line 2")
    .after("new line 1\nnew line 2\nnew line 3")
    .print(System.out);

Log

Terminal.log()
    .info("Started")
    .warn("Deprecation notice")
    .error("Something failed")
    .withTimestamp()
    .print(System.out);

// Only WARN and ERROR (e.g. for production)
Terminal.log()
    .info("Hidden")
    .warn("Visible")
    .error("Visible")
    .minLevel(Log.Level.WARN)
    .print(System.out);

(Use import dev.jakub.terminal.components.Log; for Log.Level.)

Timeline

Terminal.timeline()
    .event("2024-01-01", "First release")
    .event("2024-06-01", "Added SelectList")
    .event("2025-01-01", "GitHub Packages")
    .print(System.out);

Heatmap

Terminal.heatmap()
    .row("Mon", 10, 20, 5, 30)
    .row("Tue", 15, 25, 10, 20)
    .row("Wed", 5, 15, 25, 35)
    .print(System.out);

Chart (sparkline / bar)

Terminal.chart()
    .data(1.0, 2.0, 1.5, 3.0, 2.5)
    .height(5)
    .print(System.out);

Badge & notification

Terminal.badge("OK", Color.GREEN).println();
Terminal.badge("WARN", Color.YELLOW).print(System.out);

Terminal.notify("Done!", Notification.Type.SUCCESS);
Terminal.notify("Warning", Notification.Type.WARNING);
Terminal.notify("Error", Notification.Type.ERROR);
Terminal.notify("Info", Notification.Type.INFO);

(Use import dev.jakub.terminal.components.Notification;.)

Code block

Terminal.code("java")
    .line("public static void main(String[] args) {")
    .line("    System.out.println(\"Hello\");")
    .line("}")
    .lineNumbers()
    .print(System.out);

Help (CLI usage)

Terminal.help()
    .title("Options")
    .option("-v, --verbose", "Enable verbose output")
    .option("-h, --help", "Show this help")
    .option("--file <path>", "Input file path")
    .print(System.out);

Clear screen & cursor

Terminal.clearScreen();       // Clear terminal (ANSI)
Terminal.cursorTo(1, 1);      // Move cursor to row 1, col 1 (1-based)

No-op when ANSI is disabled.

SysInfo

Terminal.sysinfo().print(System.out);

Markdown

Terminal.markdown("# Title\n\n**Bold** and *italic*.\n\n- Item 1\n- Item 2\n\n---")
    .print(System.out);

Table of contents

Terminal.toc()
    .section("Introduction").sub("Overview").sub("Install")
    .section("API").sub("Reference")
    .section("Examples")
    .print(System.out);

---

For more, see the README and the source.