External commands

TUI4J provides two ways to hand control to something outside your application: exec launches an external process while the TUI steps aside, and suspend sends the process to the background so the shell can take over. Both patterns restore the TUI cleanly when control returns.

Launching an external process with ExecProcessMessage

Command.execProcess(process, outputHandler, errorHandler) pauses the TUI renderer, runs the external process with full terminal access, then resumes the TUI and dispatches an ExecCompletedMessage when the process exits. This is the right choice for spawning interactive programs like text editors, pagers, or sub-shells.

import com.williamcallahan.tui4j.compat.bubbletea.*;
import java.io.IOException;

private UpdateResult<? extends Model> openEditor() {
    String editor = System.getenv("EDITOR");
    if (editor == null || editor.isBlank()) {
        editor = "vim";   // fallback
    }

    ProcessBuilder pb = new ProcessBuilder(editor.split("\\s+"));
    pb.redirectInput(ProcessBuilder.Redirect.INHERIT);
    pb.redirectOutput(ProcessBuilder.Redirect.INHERIT);
    pb.redirectError(ProcessBuilder.Redirect.INHERIT);

    try {
        Process process = pb.start();
        return UpdateResult.from(this, Command.execProcess(
                process,
                (lineNumber, bytes) -> { /* handle stdout */ },
                (lineNumber, bytes) -> { /* handle stderr */ }
        ));
    } catch (IOException e) {
        this.status = "Failed to launch editor: " + e.getMessage();
        return UpdateResult.from(this);
    }
}

Redirect stdin, stdout, and stderr to INHERIT so the external process can read from and write to the real terminal. Without this the process won’t be able to render its own UI.

Handling ExecCompletedMessage

When the process exits, TUI4J dispatches an ExecCompletedMessage to your update() method. Inspect it to determine whether the process succeeded:

import com.williamcallahan.tui4j.compat.bubbletea.ExecCompletedMessage;

// ExecCompletedMessage fields:
// int exitCode()      — process exit code
// Throwable error()  — execution error, or null if none
// boolean success()  — true when exitCode == 0 and error == null
// String errorMessage() — human-readable error, or null on success

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof KeyPressMessage key) {
        return switch (key.key()) {
            case "e", "E" -> openEditor();
            case "q", "Q" -> UpdateResult.from(this, QuitMessage::new);
            default       -> UpdateResult.from(this);
        };
    }

    if (msg instanceof ExecCompletedMessage completed) {
        if (completed.success()) {
            this.status = "Editor closed successfully.";
        } else if (completed.error() != null) {
            this.status = "Error: " + completed.error().getMessage();
        } else {
            this.status = "Editor exited with code " + completed.exitCode();
        }
        return UpdateResult.from(this);
    }

    return UpdateResult.from(this);
}

Complete example

public class ExecExample implements Model {

    private String status = "Press 'e' to open your $EDITOR";

    @Override
    public Command init() {
        return Command.setWindowTitle("Exec Example");
    }

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof KeyPressMessage key) {
            return switch (key.key()) {
                case "e", "E" -> openEditor();
                case "q", "Q" -> UpdateResult.from(this, QuitMessage::new);
                default       -> UpdateResult.from(this);
            };
        }

        if (msg instanceof ExecCompletedMessage completed) {
            this.status = completed.success()
                ? "Editor closed successfully."
                : "Editor error: " + completed.errorMessage();
            return UpdateResult.from(this);
        }

        return UpdateResult.from(this);
    }

    private UpdateResult<? extends Model> openEditor() {
        String editor = System.getenv("EDITOR");
        if (editor == null || editor.isBlank()) {
            this.status = "Set the $EDITOR environment variable first.";
            return UpdateResult.from(this);
        }

        this.status = "Opening " + editor + "...";

        ProcessBuilder pb = new ProcessBuilder(editor.split("\\s+"));
        pb.redirectInput(ProcessBuilder.Redirect.INHERIT);
        pb.redirectOutput(ProcessBuilder.Redirect.INHERIT);
        pb.redirectError(ProcessBuilder.Redirect.INHERIT);

        try {
            Process process = pb.start();
            return UpdateResult.from(this, Command.execProcess(
                    process,
                    (n, b) -> {},
                    (n, b) -> {}
            ));
        } catch (IOException e) {
            this.status = "Failed to open editor: " + e.getMessage();
            return UpdateResult.from(this);
        }
    }

    @Override
    public String view() {
        return "Status: " + status + "\n\nPress 'e' to edit, 'q' to quit.\n";
    }

    public static void main(String[] args) {
        new Program(new ExecExample()).run();
    }
}

Suspending the TUI

SuspendMessage sends the TUI process to the background (equivalent to Ctrl+Z in a shell). The terminal is restored to normal and the shell regains control. When the user brings the process back to the foreground (fg), TUI4J dispatches a ResumeMessage and redraws the interface.

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof ResumeMessage) {
        // TUI is visible again — clear any "suspended" state
        this.suspending = false;
        return UpdateResult.from(this);
    }

    if (msg instanceof KeyPressMessage key) {
        return switch (key.key()) {
            case "ctrl+z" -> {
                this.suspending = true;
                yield UpdateResult.from(this, SuspendMessage::new);
            }
            case "q", "esc" -> UpdateResult.from(this, QuitMessage::new);
            default         -> UpdateResult.from(this);
        };
    }

    return UpdateResult.from(this);
}

@Override
public String view() {
    if (suspending) return "";   // blank during the suspend transition
    return "\nPress ctrl-z to suspend, q to quit.\n";
}

Exec vs suspend

	Exec	Suspend
Use when	You want to launch a specific program and know when it exits	You want the user to reach the shell freely, then return
What happens	TUI steps aside, process runs, `ExecCompletedMessage` fires on exit	Process is backgrounded; shell takes over until `fg`
Platform	All platforms	Unix-like systems (Linux, macOS)
Completion callback	`ExecCompletedMessage` with exit code and error	`ResumeMessage` with no exit metadata

SuspendMessage has no effect on Windows because the platform does not support POSIX job control. Use exec if you need to hand off to an external process on Windows.

When a user opens an editor via exec, render a blank or minimal view() between the time you return Command.execProcess(...) and when you receive ExecCompletedMessage. The TUI renderer will not display during the exec, but this prevents a flash of stale content if the terminal is resized during the process.

Mouse input

Handle clicks and motion in your TUI

Spring Boot integration

Embed TUI4J into a Spring Boot app

Get Started

Core Concepts

Components

Guides

Compatibility

External commands

Launching an external process with ExecProcessMessage

Handling ExecCompletedMessage

Complete example

Suspending the TUI

Exec vs suspend

Mouse input

Spring Boot integration

​Launching an external process with ExecProcessMessage

​Handling ExecCompletedMessage

​Complete example

​Suspending the TUI

​Exec vs suspend

Mouse input

Spring Boot integration

Launching an external process with ExecProcessMessage

Handling ExecCompletedMessage

Complete example

Suspending the TUI

Exec vs suspend