---

title: Environment variables description: Configure OpenTUI runtime, diagnostics, assets, and terminal overrides skill: entry: true intents: [env, environment, configuration, flags]

Environment variables

OpenTUI reads these values from process.env. Bun loads .env automatically. With Node.js, use the shell or Node's environment-file support.

OpenTUI parses most registered values on first use and caches the result. Set each value before the read time in the tables below. Registered boolean values treat true, 1, on, and yes as true without case sensitivity. Other explicit values are false.

The tables list explicit OpenTUI settings. Terminal and clipboard detection also read host variables such as TERM, TMUX, ZELLIJ, SSH variables, DISPLAY, and WAYLAND_DISPLAY. Those values describe the host environment. They are not OpenTUI configuration keys. Read Terminal capabilities for detection.

Stable configuration

OPENTUI_FORCE_WCWIDTH, OPENTUI_FORCE_UNICODE, and OPENTUI_FORCE_NOZWJ are native presence flags. Any value, including 0 or false, enables the override. Leave the variable unset to disable it.

OPENTUI_GRAPHICS recognizes only lowercase false or 0 to disable graphics detection. Lowercase true or 1 keeps automatic detection. Other values do not change automatic behavior. OPENTUI_IMAGE_PROTOCOL is case-insensitive. Invalid values keep auto. Forcing an unsupported protocol can produce incorrect output.

OPENTUI_FORCE_EXPLICIT_WIDTH=true or 1 forces explicit-width support. false or 0 disables it and skips OSC 66 queries on older terminals.

OPENTUI_NOTIFICATION_PROTOCOL accepts osc9, osc777, osc99, and none without case sensitivity. 0, false, and off also disable notifications. 1, true, and on keep automatic detection. Use an override only when terminal detection selects the wrong protocol. OPENTUI_NOTIFICATIONS=0, false, or off disables notifications without changing other capability detection.

OTUI_PALETTE_IDLE_TIMEOUT_MS bounds palette detection when a terminal reports OSC support but does not answer color queries. OTUI_USE_CONSOLE=false disables global console.* capture. The consoleMode renderer option changes only the overlay surface.

When set, OTUI_USE_ALTERNATE_SCREEN overrides screenMode. A true value forces "alternate-screen". Any other explicit value forces "main-screen". When set, OTUI_OVERRIDE_STDOUT overrides externalOutputMode. A true value captures stdout only in "split-footer". Any other explicit value forces passthrough.

Diagnostics

OTUI_TS_STYLE_WARN behaves like a presence string. Any explicit nonempty value, including false, enables warnings.

OTUI_NO_NATIVE_RENDER does not stop the render loop. In "split-footer" mode, output flushing can still write ANSI cursor movement and clear sequences. OTUI_DUMP_CAPTURES runs from the renderer exit handler. Calling renderer.destroy() directly does not trigger that dump by itself.

Build-time and startup values

OPENTUI_LIBC

On Linux, an unset value, an empty value, or glibc selects the glibc package. The value musl selects the musl package. Any other nonempty value throws. Set the value before the first Core import. A standalone Bun build can define process.env.OPENTUI_LIBC at build time so tree shaking keeps only the target branch. See Runtime and platform support and Standalone executables.

OTUI_ASSET_ROOT

OTUI_ASSET_ROOT relocates the native library, parser worker, default parser assets, and Tree-sitter WASM. The value must be an absolute directory. Put every file beneath it with the exact key from getNodeAssets().

Set the variable before importing or executing bundled Core code. An empty value is unset. When a nonempty root is set, every requested asset must exist beneath it. A missing asset throws, and OpenTUI does not use a package-relative fallback. See Standalone executables.

OTUI_TREE_SITTER_WORKER_PATH

Set the worker path before the first TreeSitterClient starts its worker. Setting it after Core import is valid if no Tree-sitter worker started. An explicit client workerPath option takes precedence over this variable.

Security-sensitive diagnostics

OTUI_STDIN_LOG=/tmp/opentui-stdin.bin records stdin before parsing. The renderer truncates the file when it starts and writes to it synchronously. The binary data can contain passwords and other sensitive input. Use this option only for short debugging sessions, and protect the recorded file. Treat OTUI_DEBUG input captures and OTUI_DUMP_CAPTURES output as sensitive data too.

OTUI_GHOSTTY_LOG_LEVEL accepts error, warn, info, or debug (err and warning are aliases). The selected level includes all more severe messages. Unset or invalid values disable Ghostty logs. Standard-library logs outside the recognized Ghostty scopes are always discarded.

Remote sessions

A renderer with remote: true forwards no local environment keys to native terminal detection by default. Add only the required names to forwardEnvKeys. This rule prevents local terminal overrides from changing an unrelated remote terminal.

See Troubleshooting for errors related to native loading, runtime assets, terminal overrides, and Tree-sitter workers.