Environment Variables

FrankenTUI honors a small set of environment variables that control the harness, runtime, deterministic E2E runs, telemetry export, and terminal- capability detection. This is the canonical list.

Env vars are checked at startup or at the point of use (never polled). Unless noted otherwise, unset is equivalent to the default.

Harness (`ftui-harness` / demo showcase)

These vars configure the reference harness and the demo showcase.

Var	Default	Values	Purpose	Referenced by
`FTUI_HARNESS_SCREEN_MODE`	`inline`	`inline` \| `alt`	Which screen mode the harness starts in	`ftui-harness`, `ftui-demo-showcase`
`FTUI_HARNESS_UI_HEIGHT`	`12`	integer rows	Rows reserved for the pinned UI region (inline mode)	`ftui-harness`, `ftui-demo-showcase`
`FTUI_HARNESS_VIEW`	—	view name (e.g. `dashboard`)	Pick a specific demo view	`ftui-demo-showcase`
`FTUI_HARNESS_ENABLE_MOUSE`	`false`	`true` \| `false`	Enable mouse capture	`ftui-harness`
`FTUI_HARNESS_ENABLE_FOCUS`	`false`	`true` \| `false`	Enable focus event reporting	`ftui-harness`
`FTUI_HARNESS_LOG_LINES`	`25`	integer	Number of log lines visible above the UI region	`ftui-harness`
`FTUI_HARNESS_LOG_MARKUP`	`false`	`true` \| `false`	Render Pango-like markup in log lines	`ftui-harness`
`FTUI_HARNESS_LOG_FILE`	—	path	Write log output to a file in addition to the UI	`ftui-harness`
`FTUI_HARNESS_EXIT_AFTER_MS`	`0`	integer ms	Auto-exit the harness after N ms (0 disables)	`ftui-harness`

Example:


FTUI_HARNESS_VIEW=dashboard cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=visual_effects cargo run -p ftui-demo-showcase

See /demo-showcase/overview for the full screen catalog.

Runtime Rollout

Var	Default	Values	Purpose	Referenced by
`FTUI_RUNTIME_LANE`	`structured`	`legacy` \| `structured` \| `asupersync`	Select the execution backend (see rollout lanes)	`ftui-runtime`
`FTUI_ROLLOUT_POLICY`	`off`	`off` \| `shadow` \| `enabled`	Rollout behavior — `shadow` runs both lanes and compares	`ftui-runtime`

Pair FTUI_ROLLOUT_POLICY=shadow with FTUI_RUNTIME_LANE=asupersync to run the new lane alongside the current one and emit a rollout scorecard.

Deterministic E2E

Var	Default	Values	Purpose	Referenced by
`E2E_DETERMINISTIC`	`0`	`0` \| `1`	Enable deterministic fixtures (fixed seed + stepped virtual clock)	`ftui-harness`, `scripts/`
`E2E_SEED`	`0`	u64	Seed for all PRNGs and simulators	`ftui-harness`, `scripts/`
`E2E_TIME_STEP_MS`	`16`	integer ms	Virtual clock step per frame	`ftui-harness`, `scripts/`

Example:


E2E_DETERMINISTIC=1 E2E_SEED=0 E2E_TIME_STEP_MS=100 ./scripts/e2e_test.sh
E2E_DETERMINISTIC=1 E2E_SEED=42 ./scripts/demo_showcase_e2e.sh

See /testing/determinism-fixtures for the full determinism contract.

Telemetry (OpenTelemetry)

Var	Default	Values	Purpose	Referenced by
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	URL	OTLP endpoint for spans + events	`ftui-runtime/telemetry`
`OTEL_SERVICE_NAME`	`ftui-runtime`	string	Overrides the `service.name` attribute	`ftui-runtime/telemetry`
`FTUI_TELEMETRY_VERBOSE`	`false`	`true` \| `false`	Enable verbose (soft-redacted) fields	`ftui-runtime/telemetry`

Only active when the ftui-runtime/telemetry feature is enabled. See /reference/feature-flags and /reference/telemetry-events.

Terminal Probes

Standard vars used by the terminal capabilities probe.

Var	Default	Values	Purpose	Referenced by
`TERM`	—	e.g. `xterm-256color`, `screen-256color`	Terminal type (informs color capability guess)	`ftui-core`
`COLORTERM`	—	`truecolor`, `24bit`	24-bit color advertisement	`ftui-core`
`NO_COLOR`	—	any non-empty	Disable color output unconditionally	`ftui-core`
`TMUX`	—	set by tmux	Detection: running under tmux	`ftui-core`
`STY`	—	set by GNU screen	Detection: running under GNU screen	`ftui-core`
`ZELLIJ`	—	set by zellij	Detection: running under zellij	`ftui-core`
`KITTY_WINDOW_ID`	—	set by Kitty	Detection: running under Kitty	`ftui-core`

These drive TerminalCapabilities and the inline-mode strategy selector in ADR-001.

GPU / Visual FX

Var	Default	Values	Purpose	Referenced by
`FTUI_FX_GPU_DISABLE`	`0`	`0` \| `1`	Force CPU FX path even when `fx-gpu` is enabled	`ftui-extras`
`FTUI_FX_GPU_FORCE_FAIL`	`0`	`0` \| `1`	Test hook: simulate GPU init failure	`ftui-extras` (tests)

Glyph Policy Overrides

Deterministic glyph selection — applied before rendering.

Var	Default	Values	Purpose	Referenced by
`FTUI_GLYPH_MODE`	auto	`unicode` \| `ascii`	Force overall glyph mode	`ftui-render`
`FTUI_GLYPH_EMOJI`	auto	`0` \| `1`	Enable/disable emoji (ignored in ASCII mode)	`ftui-render`
`FTUI_NO_EMOJI`	—	`0` \| `1`	Legacy alias (`1` disables emoji)	`ftui-render`
`FTUI_GLYPH_LINE_DRAWING`	auto	`0` \| `1`	Enable/disable Unicode box drawing glyphs	`ftui-render`
`FTUI_GLYPH_ARROWS`	auto	`0` \| `1`	Enable/disable Unicode arrows/symbols	`ftui-render`
`FTUI_GLYPH_DOUBLE_WIDTH`	auto	`0` \| `1`	Override double-width glyph support	`ftui-render`

Notes:

Overrides are deterministic and applied before rendering.
FTUI_GLYPH_MODE=ascii forces line drawing, arrows, and emoji off regardless of other flags.
If double-width is disabled, emoji defaults off unless explicitly overridden.

Test Profiles

Var	Default	Values	Purpose	Referenced by
`FTUI_TEST_PROFILE`	—	profile name	Select a simulated capability profile	`ftui-harness`
`FTUI_TEST_PROFILE_COMPARE`	—	`report` \| `strict`	Compare profiles in one run	`ftui-harness`

Profile names include dumb, screen, tmux, windows-console. Snapshot filenames are suffixed with __<profile> so each profile keeps its own baselines. See /reference/terminal-compatibility for the quirk catalog.

Snapshot Blessing

Var	Default	Values	Purpose	Referenced by
`BLESS`	`0`	`0` \| `1`	Update `.txt` / `.jsonl` snapshots instead of comparing	`ftui-harness`, CI


BLESS=1 cargo test -p ftui-harness

See /testing/snapshot-tests.