Home > FAQs > How to see logs

How do I see OpenCues logs?

One file, one command. Every host writes its runtime log to /tmp/opencues.log, and opencues logs shows you the last 50 lines; add --tail to follow it live while you reproduce a problem (Ctrl+C to exit).

Turning on detail

By default the log is quiet. The detail switch is the debug-mode scalar, and the quickest flip is opencues debug on (bare opencues debug prints the current state, off turns it back off). Hot-reload picks the change up within a couple of seconds on the next keystroke, so you can toggle it mid-session without restarting the host. The same scalar is cyclable in-text via opencues settings _.

With debug on, the log gets genuinely informative lines. A transform-blank dispatch, for example, logs its timing, the verdict it reached, and the instruction and target it extracted from your text, so you can see exactly how your _ was interpreted rather than guessing. The repo's own FAQ uses exactly this workflow to debug "why did my rewrite do that": find the TransformBlank FUSED line, read the parsed instruction, and the mystery usually dissolves. Since every host shares the one file, lines carry a host prefix, which keeps a session with two hosts open readable.

The debugging ladder

Logs are the third rung, not the first. The order that wastes the least of your time:

opencues doctor: structural problems (missing keys, stale installs), each with a suggested fix.
opencues which: the live path layout with exists/missing markers, for "is it even looking where I think it is" questions.
opencues logs --tail: watch the runtime think in real time while you type the failing input in the other window.

Most reported problems die on the first rung; the log is for the cases where something registered, fired, and did the wrong thing.

The other log files

Two more locations matter occasionally, both also under /tmp:

/tmp/opencues-install-<host>.log: installer output, the place to look when an opencues install step fails.
/tmp/opencues-status-<pid>.json and /tmp/opencues-cursor-state-<pid>.json: per-process IPC state files, useful mainly when reporting a bug.

Honest scope notes

Because the files live in /tmp, they don't survive a reboot, which is the right default for logs that can contain fragments of what you typed. The toggle is the debug-mode scalar (off by default), not an environment variable: there is no DEBUG=... switch to export. And the log is plain text, so ordinary tooling applies; grepping it for a blank's name or for the word verdict narrows a noisy session fast. If you file an issue, the most useful attachment is the relevant logs --tail excerpt captured with debug on while reproducing, plus the opencues doctor output.