Troubleshooting
“ctrl+↑/↓ doesn’t jump 10 lines”
Your terminal is probably intercepting the key combo before it reaches the TUI.
- iTerm2 — by default ctrl+↑/↓ is bound to “Switch to next/previous tab” or pane navigation. Either rebind those bindings in iTerm Preferences → Profiles → Keys, or use
J/K(which we’ll likely add as a fallback in a future release). - macOS Terminal.app — usually works out of the box.
- tmux — your tmux config might capture them; check
bind-key.
Verify with: cat, then press ctrl+↑ — if you see ^[[1;5A printed in the terminal, the keys are reaching the shell. If you see nothing, the terminal ate them.
“The TUI looks broken / overlaps after I resize”
The layout uses Ink’s measureElement plus a process.stdout.on("resize") listener, so resizing the terminal should reflow. If you see leftover artifacts:
- Press
rto force a reload in the current view - Quit (
Q) and relaunch — alt-screen reset takes care of the rest
If overlap persists across launches, it’s a bug — please open an issue at github.com/loguro/loguro-tools with terminal name + version.
“I pressed / but nothing happened”
The Docs view (4) owns / for its own full-text search. Press / while in Docs and the bar focuses at the top of that view, not the global filter bar.
If you wanted to filter the Logs view, press 1 first to switch back.
“The health badge shows health ?”
The /health-trend request failed. Common causes:
- Token expired — run
loguro loginagain - No project linked or wrong project — confirm with
loguro projects - Backend transient error — wait 60s, badge will re-fetch
“Saved view I created isn’t showing up”
Saved views are backend-synced — there’s no local cache. If the create silently failed (e.g. rate limit, plan limit), the status bar shows an error string at the bottom. Press r in the Saved Views list to refetch.
“Where is the docs cache?”
Inline docs are cached at:
$XDG_CONFIG_HOME/loguro/docs-cache/ # or ~/.config/loguro/docs-cache/One .md file per slug. Each entry is fresh for 24 hours. Press r in the Docs view (with a page open) to force a single re-fetch, or r on the empty state to re-scrape the entire index.
You can rm -rf the directory safely — the TUI rebuilds it on next launch.
“The TUI ate my terminal scroll buffer”
The TUI uses the alternate screen buffer (\x1b[?1049h on entry, \x1b[?1049l on exit). When you quit, your shell returns to exactly the buffer you had before launching — that’s the correct behavior.
If you want everything to stay visible after quit (no alt-screen), use loguro logs -i instead — that’s the legacy one-shot TUI which doesn’t switch buffers.
State that survives across runs
| State | Where |
|---|---|
| Auth token | $XDG_CONFIG_HOME/loguro/auth.json |
| App / project config | $XDG_CONFIG_HOME/loguro/config.json |
| Project links | $XDG_CONFIG_HOME/loguro/links.json (auto-maintained) |
| Docs cache | $XDG_CONFIG_HOME/loguro/docs-cache/*.md (24h TTL) |
| Pins, saved views, alerts | Backend — not local |
The TUI itself holds nothing persistent beyond the docs cache. Closing and reopening always starts at the Logs view (unless you pass --view=…).
Reporting issues
If something’s off, please include:
loguro --version- Terminal name + version (e.g. iTerm2 3.5.0, alacritty 0.13)
echo $TERM- What you pressed, what you saw, what you expected