This guide will help you get up and running with TamboUI quickly.

Requirements

  • Java 8 or later (Java 17+ highly recommended)

Installation

Maven

Add the snapshot repository and dependencies to your pom.xml:

<repository>
    <id>ossrh-snapshots</id>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

<dependencies>
    <!-- For Toolkit DSL (recommended) -->
    <dependency>
        <groupId>dev.tamboui</groupId>
        <artifactId>tamboui-toolkit</artifactId>
        <version>0.2.0-SNAPSHOT</version>
    </dependency>

    <!-- JLine backend (required) -->
    <dependency>
        <groupId>dev.tamboui</groupId>
        <artifactId>tamboui-jline</artifactId>
        <version>0.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

repositories {
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
        mavenContent {
            snapshotsOnly()
        }
    }
}

dependencies {
    // For Toolkit DSL (recommended)
    implementation("dev.tamboui:tamboui-toolkit:0.2.0-SNAPSHOT")

    // JLine backend (required)
    implementation("dev.tamboui:tamboui-jline:0.2.0-SNAPSHOT")
}

JBang

For quick experimentation, use JBang with inline dependencies:

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS dev.tamboui:tamboui-toolkit:LATEST
//DEPS dev.tamboui:tamboui-jline:LATEST
//REPOS https://central.sonatype.com/repository/maven-snapshots/

// Your code here...

Hello World Examples

TamboUI offers four API levels. Choose based on your needs:

API Level Best For Complexity

Toolkit DSL

Most applications - declarative, component-based UI

Low

TuiRunner

Custom event handling, animations

Medium

Immediate Mode

Maximum control, custom rendering

High

Inline Display

CLI progress bars, build output, status lines

Low

The simplest way to build a TUI application:

public class HelloDsl extends ToolkitApp {

    @Override
    protected Element render() {
        return panel("Hello",
            text("Welcome to TamboUI DSL!").bold().cyan(),
            spacer(),
            text("Press 'q' to quit").dim()
        ).rounded();
    }

    public void runApp() throws Exception {
        new HelloDsl().run();
    }
}

For more control over the event loop:

try (var tui = TuiRunner.create()) {
    tui.run(
        (event, runner) ->
            switch (event) {
                case KeyEvent k when k.isQuit() -> {
                    runner.quit();
                    yield false;
                }
                default -> false;
            },
        frame -> {
            var paragraph = Paragraph.builder()
                .text(Text.from("Hello, TamboUI! Press 'q' to quit."))
                .build();
            frame.renderWidget(paragraph, frame.area());
        }
    );
}

Using Immediate Mode

For maximum control over the terminal:

try (var backend = BackendFactory.create()) {
    backend.enableRawMode();
    backend.enterAlternateScreen();

    try (var terminal = new Terminal<>(backend)) {
        terminal.draw(frame -> {
            var paragraph = Paragraph.builder()
                .text(Text.from("Hello, Immediate Mode!"))
                .build();
            frame.renderWidget(paragraph, frame.area());
        });
    }
    // Wait for user input
    Thread.sleep(2000);
}

Using Inline Display

For CLI tools that show progress while preserving terminal history:

try (var display = InlineDisplay.create(2)) {
    for (int i = 0; i <= 100; i += 5) {
        int progress = i;
        display.render((area, buffer) -> {
            var gauge = Gauge.builder()
                .ratio(progress / 100.0)
                .label("Progress: " + progress + "%")
                .build();
            gauge.render(area, buffer);
        });
        Thread.sleep(50);
    }
    display.println("Done!");
}

Running/Debugging

Full color and input handling require a real terminal. Many build tools and IDEs do not attach one to the process, so you may see a "dumb terminal" warning or broken behavior.

If you know of better workarounds or can help advocate for improving terminal support in these tools, please let us know!

The following describes how to run and debug TamboUI apps per tool and known workarounds:

Maven

Maven normally just works, i.e. if you can run mvn exec:java then you can run TamboUI apps with no problems.

Gradle

Gradle runs Java via a daemon that has no terminal. You may see errors like:

gradle run

> Task :run
Feb 17, 2026 5:56:38 PM org.jline.utils.Log logr
WARNING: Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)

<=========--<=========----> 75% EXECUTING [8s]
> :run
^[[?2027;0$y^C⏎

Solution

Build the app, then run it from a real terminal (or your IDE’s terminal) with java -jar or jbang run. For a single runnable JAR, use the Shadow plugin (or Application plugin’s installDist); then:

./gradlew build
java -jar build/libs/my-app-1.0.0-SNAPSHOT-all.jar

With JBang you can attach a debugger: jbang run --debug build/libs/my-app-1.0.0-SNAPSHOT-all.jar

Visual Studio Code (VSCode) variants

VSCode works well with Maven, Gradle, and JBang. Use Run & Debug as usual—the easiest way to run and debug TamboUI apps.

IntelliJ IDEA

Run & Debug does not reliably get a real terminal (IntelliJ runs via Gradle/Maven in a limited environment). Workaround: build the app, then run it from the command line or IntelliJ’s built-in terminal with java -jar or jbang run.

Apache NetBeans

NetBeans has similar issues (runs via Maven/Gradle, no real terminal) and its built-in terminal is not fully compliant. Use an external terminal and run the app with java -jar or jbang run.

Eclipse

Eclipse can run classes directly, but the console and built-in terminal are not full TTYs. Use an external terminal and run with java -jar or jbang run.

Running the Demos

TamboUI includes many demo applications showcasing different features.

Without Cloning the Repository

The easiest way to explore demos is with JBang (you don’t need to clone the TamboUI repository):

# Launch the interactive demo selector
jbang demos@tamboui

From TamboUI sources

If you’ve cloned the TamboUI repository, you have more options.

Using JBang

# List available demos
jbang alias list .

# Run a specific demo
jbang sparkline-demo

Using the run-demo.sh Script

# Show interactive demo selector
./run-demo.sh

# Run a specific demo on JVM
./run-demo.sh sparkline-demo

# Run as native executable (requires GraalVM)
./run-demo.sh sparkline-demo --native

Manual Build and Run

# Build and install the demo
./gradlew :demos:sparkline-demo:installDist

# Run it
./demos/sparkline-demo/build/install/sparkline-demo/bin/sparkline-demo

Compiling to Native Image

With GraalVM installed:

./gradlew :demos:sparkline-demo:nativeCompile
./demos/sparkline-demo/build/native/nativeCompile/sparkline-demo

Next Steps