Console - OpenTUI

Overview

The console overlay provides a built-in logging and debugging interface that can be toggled on/off during runtime. It captures console.log, console.error, etc., and displays them in an interactive overlay with scrolling, searching, and log saving capabilities.

Accessing the Console

The console is available through the renderer:

import { createCliRenderer } from '@opentui/core'

const renderer = await createCliRenderer()
const console = renderer.console

ConsoleOptions

Configuration options for the console overlay.

position

'top' | 'bottom' | 'left' | 'right'

default:"'bottom'"

Console position on screen

sizePercent

number

default:30

Console size as percentage of screen (10-100)

zIndex

number

default:null

Z-index for rendering order

colorInfo

ColorInput

default:"'#00FFFF'"

Color for INFO level logs

colorWarn

ColorInput

default:"'#FFFF00'"

Color for WARN level logs

colorError

ColorInput

default:"'#FF0000'"

Color for ERROR level logs

colorDebug

ColorInput

default:"'#808080'"

Color for DEBUG level logs

colorDefault

ColorInput

default:"'#FFFFFF'"

Color for default/LOG level logs

backgroundColor

ColorInput

default:"RGBA.fromValues(0.1, 0.1, 0.1, 0.7)"

Console background color (supports transparency)

startInDebugMode

boolean

default:false

Start with debug mode enabled (shows caller info)

title

string

default:"'Console'"

Console title bar text

titleBarColor

ColorInput

default:"RGBA.fromValues(0.05, 0.05, 0.05, 0.7)"

Title bar background color

titleBarTextColor

ColorInput

default:"'#FFFFFF'"

Title bar text color

cursorColor

ColorInput

default:"'#00A0FF'"

Cursor color (when focused)

maxStoredLogs

number

default:2000

Maximum number of log entries to keep

maxDisplayLines

number

default:3000

Maximum number of display lines (wrapped)

onCopySelection

(text: string) => void

Callback when text is copied

keyBindings

ConsoleKeyBinding[]

Custom key bindings

keyAliasMap

KeyAliasMap

Custom key aliases

selectionColor

ColorInput

default:"RGBA.fromValues(0.3, 0.5, 0.8, 0.5)"

Text selection highlight color

copyButtonColor

ColorInput

default:"'#00A0FF'"

Copy button text color

Creating a Configured Console

import { createCliRenderer } from '@opentui/core'
import { RGBA } from '@opentui/core'

const renderer = await createCliRenderer({
  consoleOptions: {
    position: 'bottom',
    sizePercent: 40,
    colorInfo: '#00ffff',
    colorError: '#ff3333',
    backgroundColor: RGBA.fromValues(0, 0, 0, 0.9),
    startInDebugMode: true,
    onCopySelection: (text) => {
      // Custom copy handler (e.g., use clipboard API)
      console.log('Copied:', text)
    }
  }
})

TerminalConsole Class

Properties

visible

boolean

Whether the console is currently visible

bounds

{ x: number; y: number; width: number; height: number }

Console position and size

Methods

show()

Show the console overlay.

show(): void

hide()

Hide the console overlay.

hide(): void

toggle()

Toggle console visibility (or toggle focus if already visible).

toggle(): void

focus()

Give keyboard focus to the console.

focus(): void

blur()

Remove keyboard focus from the console.

blur(): void

clear()

Clear all console logs.

clear(): void

resize()

Resize the console (usually called automatically).

resize(width: number, height: number): void

width

number

New terminal width

height

number

New terminal height

setDebugMode()

Enable or disable debug mode (shows file/line caller info).

setDebugMode(enabled: boolean): void

enabled

boolean

Whether to enable debug mode

toggleDebugMode()

Toggle debug mode.

toggleDebugMode(): void

activate()

Activate console capture (intercepts console.log, etc.).

activate(): void

deactivate()

Deactivate console capture (restore original console).

deactivate(): void

destroy()

Destroy the console and clean up.

destroy(): void

getCachedLogs()

Get cached logs as a formatted string.

getCachedLogs(): string

string

Formatted log entries

renderToBuffer()

Render the console to a buffer (called automatically).

renderToBuffer(buffer: OptimizedBuffer): void

buffer

OptimizedBuffer

Target buffer to render to

handleMouse()

Handle mouse events (called automatically).

handleMouse(event: MouseEvent): boolean

event

MouseEvent

Mouse event to handle

boolean

Whether the event was handled

Setters

keyBindings

Set custom key bindings.

set keyBindings(bindings: ConsoleKeyBinding[])

bindings

ConsoleKeyBinding[]

Array of key binding configurations

keyAliasMap

Set custom key aliases.

set keyAliasMap(aliases: KeyAliasMap)

aliases

KeyAliasMap

Map of key aliases

onCopySelection

Set the copy selection callback.

set onCopySelection(callback: ((text: string) => void) | undefined)

callback

(text: string) => void

Callback function

Default Key Bindings

Up Arrow

key

Scroll up one line

Down Arrow

key

Scroll down one line

Shift+Up Arrow

key

Scroll to top

Shift+Down Arrow

key

Scroll to bottom

Ctrl+P

key

Move console to previous position (top → right → bottom → left)

Ctrl+O

key

Move console to next position (top → left → bottom → right)

+ or Shift+=

key

Increase console size by 5%

key

Decrease console size by 5%

Ctrl+S

key

Save logs to file (console[timestamp].log)

Ctrl+Shift+C

key

Copy selected text

Escape

key

Blur console (unfocus)

ConsoleKeyBinding

Type for console key binding configuration.

type ConsoleKeyBinding = {
  name: string
  ctrl?: boolean
  shift?: boolean
  meta?: boolean
  super?: boolean
  action: ConsoleAction
}

name

string

Key name (e.g., ‘up’, ‘down’, ‘c’, ‘s’)

ctrl

boolean

Ctrl modifier

shift

boolean

Shift modifier

ConsoleAction

Available console actions.

scroll-up - Scroll up one line
scroll-down - Scroll down one line
scroll-to-top - Scroll to the top
scroll-to-bottom - Scroll to the bottom
position-previous - Move to previous position
position-next - Move to next position
size-increase - Increase size by 5%
size-decrease - Decrease size by 5%
save-logs - Save logs to file
copy-selection - Copy selected text

ConsolePosition

Enum for console position.

enum ConsolePosition {
  TOP = 'top',
  BOTTOM = 'bottom',
  LEFT = 'left',
  RIGHT = 'right',
}

Example Usage

Basic Usage

import { createCliRenderer } from '@opentui/core'

const renderer = await createCliRenderer()

// Show console
renderer.console.show()

// Log some messages
console.log('Hello, World!')
console.info('Info message')
console.warn('Warning message')
console.error('Error message')

// Toggle console visibility
renderer.console.toggle()

Custom Configuration

import { createCliRenderer, RGBA } from '@opentui/core'

const renderer = await createCliRenderer({
  consoleOptions: {
    position: 'right',
    sizePercent: 50,
    title: 'Debug Console',
    colorError: '#ff0000',
    colorWarn: '#ffaa00',
    colorInfo: '#00aaff',
    backgroundColor: RGBA.fromValues(0.05, 0.05, 0.05, 0.95),
    startInDebugMode: true,
    keyBindings: [
      { name: 'k', ctrl: true, action: 'scroll-up' },
      { name: 'j', ctrl: true, action: 'scroll-down' },
    ],
    onCopySelection: async (text) => {
      // Use clipboard API or OSC 52
      renderer.copyToClipboardOSC52(text)
      console.log('Copied to clipboard')
    },
  },
})

renderer.console.show()

Using Console Methods

const console = renderer.console

// Show and focus
console.show()
console.focus()

// Enable debug mode (shows file:line)
console.setDebugMode(true)

// Clear logs
console.clear()

// Toggle visibility
console.toggle()

// Get cached logs
const logs = console.getCachedLogs()
console.log('Cached logs:', logs)

// Cleanup
console.destroy()

Mouse Interaction

The console supports mouse interaction:

Scroll wheel - Scroll up/down
Click and drag - Select text
Click copy button - Copy selected text (if onCopySelection is set)
Auto-scroll - Automatically scrolls when dragging near edges

Environment Variables

The console respects these environment variables:

OTUI_USE_CONSOLE - Enable/disable console capture (default: true)
SHOW_CONSOLE - Show console at startup (default: false)

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

​Overview

​Accessing the Console

​ConsoleOptions

​Creating a Configured Console

​TerminalConsole Class

​Properties

​Methods

​show()

​hide()

​toggle()

​focus()

​blur()

​clear()

​resize()

​setDebugMode()

​toggleDebugMode()

​activate()

​deactivate()

​destroy()

​getCachedLogs()

​renderToBuffer()

​handleMouse()

​Setters

​keyBindings

​keyAliasMap

​onCopySelection

​Default Key Bindings

​ConsoleKeyBinding

​ConsoleAction

​ConsolePosition

​Example Usage

​Basic Usage

​Custom Configuration

​Using Console Methods

​Mouse Interaction

​Environment Variables

Build docs developers (and LLMs) love

Overview

Accessing the Console

ConsoleOptions

Creating a Configured Console

TerminalConsole Class

Properties

Methods

show()

hide()

toggle()

focus()

blur()

clear()

resize()

setDebugMode()

toggleDebugMode()

activate()

deactivate()

destroy()

getCachedLogs()

renderToBuffer()

handleMouse()

Setters

keyBindings

keyAliasMap

onCopySelection

Default Key Bindings

ConsoleKeyBinding

ConsoleAction

ConsolePosition

Example Usage

Basic Usage

Custom Configuration

Using Console Methods

Mouse Interaction

Environment Variables