Console

Interactive console overlay for logging, debugging, and user interaction

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 · 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 · 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

meta · boolean

Meta/Alt modifier

super · boolean

Super/Cmd modifier

action · ConsoleAction

Action to perform

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)