opencues doctor is the first command to run when something misbehaves: a read-only health check across every OpenCues install on your machine that looks for common breakages and suggests the fix for each one.
What it checks
Doctor sweeps every detected integration and the shared config tree for the failure shapes that actually happen: a missing .env (so no LLM key reaches the runtime), stale patcher state, unbuilt artefacts, Node version mismatches, and per-install drift (an install whose bundled runtime is older than the source it was built from gets its own warning row). Findings come with suggested fixes, not just red marks. Real findings it surfaces include out-of-sync Chrome bundles, missing provider keys, and broken patched installs.
When to reach for it
The project's own FAQ answers "something's broken, what do I run first?" with exactly this command. The debugging ladder is:
opencues doctor: what's structurally wrong, with fixes.opencues which: the live path layout, with exists/missing markers per path.opencues logs --tail: the runtime log at/tmp/opencues.log, live.
It's also worth running before reporting a bug, since its output is the context a maintainer wants first.
Read-only by design
Doctor never mutates anything. It diagnoses; the fixes it suggests are commands you run yourself (opencues install <host>, opencues set-key ..., and so on). That makes it always safe to run, including in CI, where a --strict flag turns info-level findings into failures for gating. Checks are content-hash based, so a rebuild that changed nothing doesn't produce a false positive.
Related: OpenCues not working? · How to install OpenCues · Why is my blank not firing? · GitHub repo