Doctor and Diagnostics
When something is off, start with the doctor. It checks the external binaries and environment signals Wayland Core depends on and tells you what is missing, with install hints for your platform.
Run the doctor
Section titled “Run the doctor”wayland-core --doctorThe doctor probes external binaries (such as wlrctl, grim, chromium, and ollama) and environment signals (WAYLAND_DISPLAY, DISPLAY, BROWSERBASE_API_KEY, OLLAMA_BASE_URL). For each missing dependency it prints a per-distro install hint. It exits 1 if any required check fails on the current platform, otherwise 0, so you can gate a setup script on it.
In TUI mode the engine routes its trace output to a log file rather than the screen, so the interface stays clean. The file lives at $WAYLAND_HOME/logs/wayland-core.log (or ~/.wayland/logs/wayland-core.log when WAYLAND_HOME is unset). Tail it in another pane to watch the internals:
tail -f ~/.wayland/logs/wayland-core.logHeadless modes (--json-stream, a one-shot prompt, --no-tui, or piped output) keep writing diagnostics to stderr, so CI logs and --help print where you expect.
Turn up the verbosity
Section titled “Turn up the verbosity”The engine honors RUST_LOG at runtime. Raise it to see more:
RUST_LOG=debug wayland-core "Why did that tool fail?"Filter to a single target when the firehose is too much, for example RUST_LOG=wcore_agent=debug.
Unclean shutdowns
Section titled “Unclean shutdowns”Wayland Core arms a crash sentinel early in startup. If a previous run died without exiting cleanly, the next start detects the leftover flag and can surface that the last session ended abnormally. A clean exit removes the flag; a panic leaves it behind on purpose so the next start can report it.
Check other surfaces
Section titled “Check other surfaces”A bad provider or auth setup often shows up as a failed run rather than a doctor finding. If --doctor is clean but runs still fail, confirm your credentials and base URL with the provider and auth tooling.