Class TerminalCapabilities

java.lang.Object
org.aesh.terminal.detect.TerminalCapabilities
public final class TerminalCapabilities extends Object
Lightweight terminal capability detection.

Detects terminal features using environment variables and heuristics without requiring a terminal connection or any external dependencies.

Usage: 

// Fast heuristic detection (~1-2ms)
TerminalCapabilities caps = TerminalCapabilities.detect();

// Async detection with background color queries
TerminalCapabilities caps = TerminalCapabilities.detectAsync();
// ... do other startup work ...
caps.awaitColors(500, TimeUnit.MILLISECONDS);
int[] bg = caps.backgroundRGB(); // available once query completes

  • Method Details

    • getInstance

      public static TerminalCapabilities getInstance()
      Get the shared instance, creating it lazily via detect().

      Use setInstance(TerminalCapabilities) to inject a pre-built instance from early startup (e.g., Quarkus bootstrap). For example, call setInstance(detectAsync()) to enable background color queries before other modules initialize.

      Returns:
      the shared capabilities instance

    • setInstance

      public static void setInstance(TerminalCapabilities caps)
      Set the shared instance. Call this early in application startup to make pre-detected capabilities available to all later consumers.
      Parameters:
      caps - the pre-detected capabilities

    • detect

      public static TerminalCapabilities detect()
      Detect terminal capabilities from environment variables only. Fast (~1-2ms), no subprocess calls on Linux/macOS.
      Returns:
      the detected capabilities

    • detectFull

      public static TerminalCapabilities detectFull()
      Detect terminal capabilities with full platform theme probing.

      Same as detect() but when the theme cannot be determined from environment variables, also checks platform-specific sources:

      • macOS: defaults read -g AppleInterfaceStyle
      • Linux: gsettings (GNOME) or kreadconfig5 (KDE)
      • Windows: Apps dark mode registry key
      This may take 10-50ms due to subprocess calls.
      Returns:
      the detected capabilities with resolved theme

    • detectAsync

      public static TerminalCapabilities detectAsync()
      Detect terminal capabilities and query actual colors in the background.

      Returns immediately with heuristic results (~1-2ms). A daemon thread queries the terminal for foreground/background colors via OSC escape sequences. Use awaitColors(long, TimeUnit) to wait for the query to complete, or check backgroundRGB() / foregroundRGB() which return null until the query finishes.

      On platforms where terminal queries are not possible (Windows, pipes, containers, tmux without passthrough), the background thread completes immediately with no results and falls back to platform theme detection.

      Returns:
      the detected capabilities with background color query running

    • awaitColors

      public boolean awaitColors(long timeout, TimeUnit unit) throws InterruptedException
      Wait for the background color query to complete.

      Only relevant when created via detectAsync(). For other factory methods, this returns true immediately.

      Parameters:
      timeout - the maximum time to wait
      unit - the time unit
      Returns:
      true if the query completed, false if timed out
      Throws:
      InterruptedException - if interrupted while waiting

    • supportsTrueColor

      public boolean supportsTrueColor()
      Check if the terminal supports 24-bit true color (16 million colors).

      When created via detectAsync(), this may upgrade to true after the color query confirms true color support (terminals that respond to OSC color queries support true color).

      Returns:
      true if true color is supported

    • supports256Colors

      public boolean supports256Colors()
      Check if the terminal supports at least 256 colors. Always true when supportsTrueColor() is true.

      When created via detectAsync(), this may upgrade to true after the color query confirms 256-color support.

      Returns:
      true if 256 colors are supported

    • supportsColor

      public boolean supportsColor()
      Check if the terminal supports any color output.
      Returns:
      true if color is supported

    • imageProtocol

      public ImageProtocol imageProtocol()
      Get the image display protocol supported by this terminal.

      When created via detectAsync(), this may upgrade from NONE to SIXEL after the DA1 query confirms Sixel support.

      Returns:
      the image protocol, or ImageProtocol.NONE

    • theme

      public TerminalTheme theme()
      Get the terminal background theme.

      When created via detectAsync(), this may return a more accurate result after the color query completes (derived from the actual background RGB).

      Returns:
      the theme (DARK, LIGHT, or UNKNOWN)

    • foregroundRGB

      public int[] foregroundRGB()
      Get the queried foreground color.

      Only available after a successful color query via detectAsync().

      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • backgroundRGB

      public int[] backgroundRGB()
      Get the queried background color.

      Only available after a successful color query via detectAsync().

      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • paletteColors

      public Map<Integer,int[]> paletteColors()
      Get the queried base 16 palette colors (ANSI colors 0-15).

      Only available after a successful color query via detectAsync().

      Returns:
      map from color index (0-15) to RGB array [r, g, b], or empty map if not queried

    • paletteColor

      public int[] paletteColor(int index)
      Get a palette color by ANSI index (0-15).
      Parameters:
      index - the ANSI color index
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • black

      public int[] black()
      Returns the RGB color for ANSI black (index 0).
      Returns:
      RGB array for ANSI black (index 0), or null if not queried.

    • red

      public int[] red()
      Returns the RGB color for ANSI red (index 1).
      Returns:
      RGB array for ANSI red (index 1), or null if not queried.

    • green

      public int[] green()
      Returns the RGB color for ANSI green (index 2).
      Returns:
      RGB array for ANSI green (index 2), or null if not queried.

    • yellow

      public int[] yellow()
      Returns the RGB color for ANSI yellow (index 3).
      Returns:
      RGB array for ANSI yellow (index 3), or null if not queried.

    • blue

      public int[] blue()
      Returns the RGB color for ANSI blue (index 4).
      Returns:
      RGB array for ANSI blue (index 4), or null if not queried.

    • magenta

      public int[] magenta()
      Returns the RGB color for ANSI magenta (index 5).
      Returns:
      RGB array for ANSI magenta (index 5), or null if not queried.

    • cyan

      public int[] cyan()
      Returns the RGB color for ANSI cyan (index 6).
      Returns:
      RGB array for ANSI cyan (index 6), or null if not queried.

    • white

      public int[] white()
      Returns the RGB color for ANSI white (index 7).
      Returns:
      RGB array for ANSI white (index 7), or null if not queried.

    • brightBlack

      public int[] brightBlack()
      Returns the RGB color for bright black (index 8).
      Returns:
      RGB array for bright black (index 8), or null if not queried.

    • brightRed

      public int[] brightRed()
      Returns the RGB color for bright red (index 9).
      Returns:
      RGB array for bright red (index 9), or null if not queried.

    • brightGreen

      public int[] brightGreen()
      Returns the RGB color for bright green (index 10).
      Returns:
      RGB array for bright green (index 10), or null if not queried.

    • brightYellow

      public int[] brightYellow()
      Returns the RGB color for bright yellow (index 11).
      Returns:
      RGB array for bright yellow (index 11), or null if not queried.

    • brightBlue

      public int[] brightBlue()
      Returns the RGB color for bright blue (index 12).
      Returns:
      RGB array for bright blue (index 12), or null if not queried.

    • brightMagenta

      public int[] brightMagenta()
      Returns the RGB color for bright magenta (index 13).
      Returns:
      RGB array for bright magenta (index 13), or null if not queried.

    • brightCyan

      public int[] brightCyan()
      Returns the RGB color for bright cyan (index 14).
      Returns:
      RGB array for bright cyan (index 14), or null if not queried.

    • brightWhite

      public int[] brightWhite()
      Returns the RGB color for bright white (index 15).
      Returns:
      RGB array for bright white (index 15), or null if not queried.

    • terminalName

      public String terminalName()
      Get the detected terminal name.
      Returns:
      terminal name (e.g., "kitty", "ghostty", "iterm2", "unknown")

    • toString

      public String toString()
      Overrides:
      toString in class Object