Debugging and diagnostics

Logging, crash reports, and practical debugging patterns for TUIs.

Logs in a terminal UI

When you run a terminal UI, stdout/stderr may not be visible (alternate screen). In development, enable the built-in console overlay and write logs to it.

const renderer = await createCliRenderer({
  useConsole: true,
  consoleOptions: {
    title: "Runtime Logs",
    startInDebugMode: true,
    position: "bottom",
    height: 10,
  },
})

renderer.console.show()
console.log("Renderer started")

Crash reporting

Enable crash reporting in development so native failures are surfaced quickly. In production, log crash reports to disk or ship them to your telemetry pipeline.

CASCADE_LOG_CRASH_REPORTS=1 bun run dev

Recipe: a debug hotkey

In almost every app, add a single debug hotkey that toggles the console overlay. This makes it easy to capture runtime information without breaking the UI.

renderer.on("key", (event) => {
  if (event.ctrl && event.name === "d") {
    renderer.console.toggle()
  }
})