> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anomalyco/opentui/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Variables
> Configure OpenTUI behavior using environment variables
OpenTUI can be configured using environment variables to control rendering behavior, debugging features, and terminal capabilities.
## Setting Environment Variables
### In Shell
```bash theme={null}
# Set for current session
export OTUI_DEBUG=true
# Set for single command
OTUI_DEBUG=true bun run app.ts
```
### In Code
```typescript theme={null}
// Set before creating renderer
process.env.OTUI_DEBUG = 'true'
process.env.OTUI_SHOW_STATS = 'true'
const renderer = await createCliRenderer()
```
### In .env File
```bash theme={null}
# .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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
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`
```bash theme={null}
export SHOW_CONSOLE=true
```
### OTUI\_DUMP\_CAPTURES
Dump captured console output when the renderer exits.
**Type:** `boolean`\
**Default:** `false`
```bash theme={null}
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"`
```bash theme={null}
# 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`
```bash theme={null}
export OPENTUI_FORCE_WCWIDTH=true
```
### OPENTUI\_FORCE\_UNICODE
Force Mode 2026 Unicode support in terminal capabilities.
**Type:** `boolean`\
**Default:** `false`
```bash theme={null}
export OPENTUI_FORCE_UNICODE=true
```
### OPENTUI\_FORCE\_NOZWJ
Use no\_zwj width method (Unicode without ZWJ joining).
**Type:** `boolean`\
**Default:** `false`
```bash theme={null}
export OPENTUI_FORCE_NOZWJ=true
```
### OPENTUI\_GRAPHICS
Enable Kitty graphics protocol detection.
**Type:** `boolean`\
**Default:** `true`
```bash theme={null}
# Disable graphics detection
export OPENTUI_GRAPHICS=false
```
## Tree-sitter Variables
### OTUI\_TS\_STYLE\_WARN
Enable warnings for missing syntax styles.
**Type:** `string`\
**Default:** `false`
```bash theme={null}
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:** `""`
```bash theme={null}
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`
```bash theme={null}
export XDG_CONFIG_HOME=~/.config
```
### XDG\_DATA\_HOME
Base directory for user-specific data files.
**Type:** `string`\
**Default:** `~/.local/share`
```bash theme={null}
export XDG_DATA_HOME=~/.local/share
```
## Common Configuration Scenarios
### Development Mode
```bash theme={null}
# .env.development
OTUI_DEBUG=true
OTUI_SHOW_STATS=true
OTUI_USE_CONSOLE=true
SHOW_CONSOLE=false
OTUI_DEBUG_FFI=false
```
### Production Mode
```bash theme={null}
# .env.production
OTUI_DEBUG=false
OTUI_SHOW_STATS=false
OTUI_USE_CONSOLE=false
OTUI_OVERRIDE_STDOUT=true
```
### Performance Testing
```bash theme={null}
# .env.benchmark
OTUI_SHOW_STATS=true
OTUI_USE_CONSOLE=false
OTUI_DEBUG_FFI=false
OTUI_TRACE_FFI=false
```
### Debugging FFI Issues
```bash theme={null}
# .env.debug-ffi
OTUI_DEBUG=true
OTUI_DEBUG_FFI=true
OTUI_TRACE_FFI=true
OTUI_DUMP_CAPTURES=true
```
### Legacy Terminal Compatibility
```bash theme={null}
# .env.legacy-terminal
OPENTUI_FORCE_EXPLICIT_WIDTH=false
OPENTUI_GRAPHICS=false
OPENTUI_FORCE_WCWIDTH=true
```
## Terminal-Specific Configurations
### GNOME Terminal
```bash theme={null}
export OPENTUI_FORCE_EXPLICIT_WIDTH=false
```
### Kitty / Ghostty / WezTerm
```bash theme={null}
export OPENTUI_GRAPHICS=true
export OPENTUI_FORCE_UNICODE=true
```
### Windows Terminal
```bash theme={null}
export OPENTUI_GRAPHICS=false
```
### tmux / screen
```bash theme={null}
export OPENTUI_GRAPHICS=false
export OTUI_USE_ALTERNATE_SCREEN=true
```
## Loading Environment Files
Bun automatically loads `.env` files in this order:
1. `.env.local` (highest priority)
2. `.env.{NODE_ENV}.local`
3. `.env.{NODE_ENV}`
4. `.env`
Example project structure:
```
project/
├── .env # Default values
├── .env.development # Development overrides
├── .env.production # Production overrides
└── .env.local # Local overrides (gitignored)
```
## Environment Variable Precedence
1. **Command line** (highest priority)
```bash theme={null}
OTUI_DEBUG=true bun run app.ts
```
2. **Code**
```typescript theme={null}
process.env.OTUI_DEBUG = 'true'
```
3. **Environment files** (.env.local, .env)
4. **Shell environment**
```bash theme={null}
export OTUI_DEBUG=true
```
5. **Default values** (lowest priority)
## Troubleshooting
### Artifacts on Screen
If you see weird characters like "66" on screen:
```bash theme={null}
export OPENTUI_FORCE_EXPLICIT_WIDTH=false
```
### Performance Issues
Disable console capture:
```bash theme={null}
export OTUI_USE_CONSOLE=false
```
### Missing Console Output
Enable console:
```bash theme={null}
export OTUI_USE_CONSOLE=true
export SHOW_CONSOLE=true
```
### Debugging Not Working
Enable debug features:
```bash theme={null}
export OTUI_DEBUG=true
export OTUI_DEBUG_FFI=true
export OTUI_SHOW_STATS=true
```
## Next Steps
Optimize your application
Understand the architecture