Skip to content
ztui ztui

LogLevel

LogLevel = "debug" | "info" | "warn" | "error" | "silent"

Defined in: src/utils/logger.ts:25

Centralized logging for ztui.

Why a dedicated logger instead of console.*?

  • While a TUI is running it owns the terminal screen. Writing to stdout or stderr corrupts the rendered frame, so diagnostics must go somewhere else.
  • A single, consistent, timestamped + leveled + scoped format makes the log greppable for humans and parseable for LLM agents trying to debug a run.
  • Logging must never throw or crash the app, so every write is guarded.

Silent by default. Out of the box the logger drops everything — it writes no file and produces no output, so embedding ztui never litters the working directory or races a shared file between processes/tests. Opt in explicitly:

  • Env (read once at startup): set ZTUI_LOG_FILE=path to log to a file. ZTUI_LOG_LEVEL=debug|info|warn|error|silent sets the threshold (default info). With no ZTUI_LOG_FILE, nothing is logged regardless of level.
  • Code: logger.configure({ filePath }) to log to a file, { sink } to route formatted lines anywhere (an array, your own logger, a socket), { level } to set the threshold, or { enabled: false } to silence.
  • logger.reset() restores the environment-derived defaults (used by tests).