Environment Variables

OpenTUI can be configured using environment variables to control rendering behavior, debugging features, and terminal capabilities.

Setting Environment Variables

In Shell

# Set for current session
export OTUI_DEBUG=true

# Set for single command
OTUI_DEBUG=true bun run app.ts

In Code

// Set before creating renderer
process.env.OTUI_DEBUG = 'true'
process.env.OTUI_SHOW_STATS = 'true'

const renderer = await createCliRenderer()

In .env File

# .env
OTUI_DEBUG=true
OTUI_SHOW_STATS=true
OTUI_USE_CONSOLE=false

Bun automatically loads .env files - no need for dotenv package.

Debugging Variables

OTUI_DEBUG

Enable debug mode to capture all raw input for debugging purposes. Type: boolean
Default: false

export OTUI_DEBUG=true

When enabled:

Captures raw terminal input
Logs input sequences
Useful for debugging keyboard/mouse issues

OTUI_DEBUG_FFI

Enable debug logging for the FFI bindings between TypeScript and Zig. Type: boolean
Default: false

export OTUI_DEBUG_FFI=true

Logs:

FFI function calls
Data passed between layers
Native function execution

OTUI_TRACE_FFI

Enable detailed tracing for the FFI bindings. Type: boolean
Default: false

export OTUI_TRACE_FFI=true

Provides:

Detailed call traces
Performance metrics per call
Memory allocation tracking

OTUI_SHOW_STATS

Show the debug overlay at startup. Type: boolean
Default: false

export OTUI_SHOW_STATS=true

Displays:

FPS counter
Frame time statistics
Memory usage
Render buffer info

Rendering Variables

OTUI_NO_NATIVE_RENDER

Disable native rendering. Useful for debugging without actual terminal output. Type: boolean
Default: false

export OTUI_NO_NATIVE_RENDER=true

This will not output any ANSI sequences to the terminal. Only use for debugging.

OTUI_USE_ALTERNATE_SCREEN

Whether to use the alternate screen buffer. Type: boolean
Default: true

export OTUI_USE_ALTERNATE_SCREEN=false

When disabled:

Renders in main screen buffer
Content persists after exit
May interfere with terminal scrollback

OTUI_OVERRIDE_STDOUT

Override the stdout stream. Useful for debugging. Type: boolean
Default: true

export OTUI_OVERRIDE_STDOUT=false

Console Variables

OTUI_USE_CONSOLE

Whether to use the built-in console. When disabled, console output is not captured. Type: boolean
Default: true

export OTUI_USE_CONSOLE=false

Disable if:

You don’t need console.log capture
You want better performance
You’re using external logging

SHOW_CONSOLE

Show the console at startup. Type: boolean
Default: false

export SHOW_CONSOLE=true

OTUI_DUMP_CAPTURES

Dump captured console output when the renderer exits. Type: boolean
Default: false

export OTUI_DUMP_CAPTURES=true

Terminal Compatibility Variables

OPENTUI_FORCE_EXPLICIT_WIDTH

Force explicit width capability to true or false. Use this to fix artifacts on older terminals. Type: string
Values: "true", "1", "false", "0"

# Disable explicit width (fixes OSC 66 artifacts)
export OPENTUI_FORCE_EXPLICIT_WIDTH=false

# Enable explicit width
export OPENTUI_FORCE_EXPLICIT_WIDTH=true

Set to false or 0 on GNOME Terminal, Konsole, or xterm to prevent “66” artifacts.

When set to "false" or "0":

Prevents OSC 66 detection queries
Disables explicit width feature
Falls back to standard width calculation
No visual artifacts on unsupported terminals

OPENTUI_FORCE_WCWIDTH

Use wcwidth for character width calculations. Type: boolean
Default: false

export OPENTUI_FORCE_WCWIDTH=true

OPENTUI_FORCE_UNICODE

Force Mode 2026 Unicode support in terminal capabilities. Type: boolean
Default: false

export OPENTUI_FORCE_UNICODE=true

OPENTUI_FORCE_NOZWJ

Use no_zwj width method (Unicode without ZWJ joining). Type: boolean
Default: false

export OPENTUI_FORCE_NOZWJ=true

OPENTUI_GRAPHICS

Enable Kitty graphics protocol detection. Type: boolean
Default: true

# Disable graphics detection
export OPENTUI_GRAPHICS=false

Tree-sitter Variables

OTUI_TS_STYLE_WARN

Enable warnings for missing syntax styles. Type: string
Default: false

export OTUI_TS_STYLE_WARN=true

Useful when:

Developing syntax highlighting themes
Debugging missing style definitions
Auditing theme coverage

OTUI_TREE_SITTER_WORKER_PATH

Path to the TreeSitter worker. Type: string
Default: ""

export OTUI_TREE_SITTER_WORKER_PATH=/path/to/worker.js

XDG Base Directory Variables

XDG_CONFIG_HOME

Base directory for user-specific configuration files. Type: string
Default: ~/.config

export XDG_CONFIG_HOME=~/.config

XDG_DATA_HOME

Base directory for user-specific data files. Type: string
Default: ~/.local/share

export XDG_DATA_HOME=~/.local/share

Common Configuration Scenarios

Development Mode

# .env.development
OTUI_DEBUG=true
OTUI_SHOW_STATS=true
OTUI_USE_CONSOLE=true
SHOW_CONSOLE=false
OTUI_DEBUG_FFI=false

Production Mode

# .env.production
OTUI_DEBUG=false
OTUI_SHOW_STATS=false
OTUI_USE_CONSOLE=false
OTUI_OVERRIDE_STDOUT=true

Performance Testing

# .env.benchmark
OTUI_SHOW_STATS=true
OTUI_USE_CONSOLE=false
OTUI_DEBUG_FFI=false
OTUI_TRACE_FFI=false

Debugging FFI Issues

# .env.debug-ffi
OTUI_DEBUG=true
OTUI_DEBUG_FFI=true
OTUI_TRACE_FFI=true
OTUI_DUMP_CAPTURES=true

Legacy Terminal Compatibility

# .env.legacy-terminal
OPENTUI_FORCE_EXPLICIT_WIDTH=false
OPENTUI_GRAPHICS=false
OPENTUI_FORCE_WCWIDTH=true

Terminal-Specific Configurations

GNOME Terminal

export OPENTUI_FORCE_EXPLICIT_WIDTH=false

Kitty / Ghostty / WezTerm

export OPENTUI_GRAPHICS=true
export OPENTUI_FORCE_UNICODE=true

Windows Terminal

export OPENTUI_GRAPHICS=false

tmux / screen

export OPENTUI_GRAPHICS=false
export OTUI_USE_ALTERNATE_SCREEN=true

Loading Environment Files

Bun automatically loads .env files in this order:

.env.local (highest priority)
.env.{NODE_ENV}.local
.env.{NODE_ENV}
.env

Example project structure:

project/
├── .env                 # Default values
├── .env.development    # Development overrides
├── .env.production     # Production overrides
└── .env.local         # Local overrides (gitignored)

Environment Variable Precedence

Command line (highest priority)
```
OTUI_DEBUG=true bun run app.ts
```
Code
```
process.env.OTUI_DEBUG = 'true'
```
Environment files (.env.local, .env)
Shell environment
```
export OTUI_DEBUG=true
```
Default values (lowest priority)

Troubleshooting

Artifacts on Screen

If you see weird characters like “66” on screen:

export OPENTUI_FORCE_EXPLICIT_WIDTH=false

Performance Issues

Disable console capture:

export OTUI_USE_CONSOLE=false

Missing Console Output

Enable console:

export OTUI_USE_CONSOLE=true
export SHOW_CONSOLE=true

Debugging Not Working

Enable debug features:

export OTUI_DEBUG=true
export OTUI_DEBUG_FFI=true
export OTUI_SHOW_STATS=true

Getting Started

Core Concepts

Guides

Framework Integrations

Advanced

​Setting Environment Variables

​In Shell

​In Code

​In .env File

​Debugging Variables

​OTUI_DEBUG

​OTUI_DEBUG_FFI

​OTUI_TRACE_FFI

​OTUI_SHOW_STATS

​Rendering Variables

​OTUI_NO_NATIVE_RENDER

​OTUI_USE_ALTERNATE_SCREEN

​OTUI_OVERRIDE_STDOUT

​Console Variables

​OTUI_USE_CONSOLE

​SHOW_CONSOLE

​OTUI_DUMP_CAPTURES

​Terminal Compatibility Variables

​OPENTUI_FORCE_EXPLICIT_WIDTH

​OPENTUI_FORCE_WCWIDTH

​OPENTUI_FORCE_UNICODE

​OPENTUI_FORCE_NOZWJ

​OPENTUI_GRAPHICS

​Tree-sitter Variables

​OTUI_TS_STYLE_WARN

​OTUI_TREE_SITTER_WORKER_PATH

​XDG Base Directory Variables

​XDG_CONFIG_HOME

​XDG_DATA_HOME

​Common Configuration Scenarios

​Development Mode

​Production Mode

​Performance Testing

​Debugging FFI Issues

​Legacy Terminal Compatibility

​Terminal-Specific Configurations

​GNOME Terminal

​Kitty / Ghostty / WezTerm

​Windows Terminal

​tmux / screen

​Loading Environment Files

​Environment Variable Precedence

​Troubleshooting

​Artifacts on Screen

​Performance Issues

​Missing Console Output

​Debugging Not Working

​Next Steps

Performance

Native Zig Core

Build docs developers (and LLMs) love

Setting Environment Variables

In Shell

In Code

In .env File

Debugging Variables

OTUI_DEBUG

OTUI_DEBUG_FFI

OTUI_TRACE_FFI

OTUI_SHOW_STATS

Rendering Variables

OTUI_NO_NATIVE_RENDER

OTUI_USE_ALTERNATE_SCREEN

OTUI_OVERRIDE_STDOUT

Console Variables

OTUI_USE_CONSOLE

SHOW_CONSOLE

OTUI_DUMP_CAPTURES

Terminal Compatibility Variables

OPENTUI_FORCE_EXPLICIT_WIDTH

OPENTUI_FORCE_WCWIDTH

OPENTUI_FORCE_UNICODE

OPENTUI_FORCE_NOZWJ

OPENTUI_GRAPHICS

Tree-sitter Variables

OTUI_TS_STYLE_WARN

OTUI_TREE_SITTER_WORKER_PATH

XDG Base Directory Variables

XDG_CONFIG_HOME

XDG_DATA_HOME

Common Configuration Scenarios

Development Mode

Production Mode

Performance Testing

Debugging FFI Issues

Legacy Terminal Compatibility

Terminal-Specific Configurations

GNOME Terminal

Kitty / Ghostty / WezTerm

Windows Terminal

tmux / screen

Loading Environment Files

Environment Variable Precedence

Troubleshooting

Artifacts on Screen

Performance Issues

Missing Console Output

Debugging Not Working

Next Steps