A terminal log viewer that understands your logs.
Auto-detects formats. Parses structure. Surfaces what matters.

Quickstart · Features · Formats · Keybindings

---

Lumolog is a TUI log viewer built for developers, SREs, and security teams. Point it at any log file and it automatically detects the format, parses structured fields, colorizes by severity, and gives you interactive tools to search, filter, and investigate — right from your terminal.

Most log viewers just make text pretty. Lumolog understands your logs — it knows what's an IP address, what's a timestamp, what's an error level, and lets you act on all of it.

Quickstart

Install

1. Install Rust (if you don't have it):

# macOS / Linux / WSL
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (download and run the installer)
# https://win.rustup.rs/x86_64

2. Build and install lumolog:

git clone https://github.com/HopperShell/lumolog.git
cd lumolog
cargo install --path .

Usage

# View a log file
lumolog app.log

# Pipe from any command
docker compose logs 2>&1 | lumolog
kubectl logs deploy/api | lumolog
cat /var/log/syslog | lumolog

# Follow mode (like tail -f)
lumolog -f /var/log/app.log
docker logs -f mycontainer 2>&1 | lumolog -f

Lumolog auto-detects the log format. No configuration needed.

Features

Auto-Format Detection & Highlighting

Lumolog samples the first lines of input and automatically identifies the log format. Structured fields are parsed and colorized — levels get color-coded badges, timestamps are dimmed, and inline patterns (IPs, URLs, UUIDs, file paths, HTTP methods, key=value pairs) are highlighted throughout.

Eight formats are detected automatically — see Supported Formats.

Search & Filter

Press / to open the filter bar. Type a substring and matching lines are shown instantly with highlighted matches. If no exact matches are found, lumolog falls back to fuzzy matching automatically — type "conref" to find "connection refused".

The filter bar shows a live match count as you type: / error (142 matches) or / conref (~38 fuzzy).

Here, pressing / opens the filter bar and typing a query instantly narrows the view to matching lines — non-matching lines are hidden and matches are highlighted in yellow. The match count updates live as you type.

Level Filtering & Stats Bar

A colored stats bar shows log level counts at a glance — ERR:42 WRN:130 INF:1204. Click any badge to filter to that level and above. Click again to clear.

You can also cycle through levels with v (stricter) and V (looser) from the keyboard. Level filtering composes with text search and time range — stack them to narrow down exactly what you need.

Time Range Selection

A sparkline density bar at the top shows log volume over time. Press t to enter time range mode and select a window with keyboard controls, or click and drag directly on the sparkline.

Quick presets: 1 for last 5 minutes, 2 for 15 minutes, 3 for 1 hour, 4 for 24 hours.

Time filtering composes with all other filters — combine a time window with a level filter and text search to isolate exactly the incident you're investigating.

The sparkline at the top visualizes log density over time — spikes show bursts of activity. Click and drag across it to select a time window, and only logs within that range are shown. Release to apply the filter.

Click-to-Action

Click any highlighted token to open a context menu with relevant actions:

• IP addresses — filter by value or look up on AbuseIPDB
• URLs — filter by value or open in browser
• UUIDs, paths, HTTP methods, key=value pairs — filter by value

Clicking a highlighted IP address opens a context menu — choose "Filter" to narrow the view to all log lines containing that IP, or choose "AbuseIPDB" to open a threat intelligence lookup in your browser.

JSON Pretty-Print

Press p to expand JSON log lines into indented, readable JSON. Scroll through expanded entries naturally — the viewport accounts for multi-line expansion. Press p again to return to compact view.

Follow Mode

Use -f to tail a log file or stream stdin in real time. New lines appear at the bottom as they arrive. Press Space to pause and investigate, then Space again to resume. Works with files and piped stdin.

lumolog -f /var/log/app.log
docker logs -f mycontainer 2>&1 | lumolog -f

Cursor Mode & Copy

Press Enter to activate cursor mode. A highlighted bar tracks your position as you move through lines with j/k. From cursor mode:

• y — yank the current line to clipboard
• Y — yank all filtered lines to clipboard
• s — filter to structurally similar lines (same template, different values)

Similar-line filtering is powerful for noisy logs — it computes a structural template by replacing IPs, numbers, UUIDs, URLs, and timestamps with wildcards, then shows all lines matching that shape.

Pressing Enter activates cursor mode — a highlighted bar appears that you can move with j/k. Press y to copy the current line to your clipboard. The status bar briefly flashes "YANKED" to confirm.

To extract multiple lines at once, apply a filter first — use / to search or v to filter by level — then press Y to yank every visible line to your clipboard in one shot. Useful for pulling all errors into an incident report or Slack message.

AI-Powered Query & Analysis

Lumolog can connect to any LLM — cloud (Claude, OpenAI) or local (Ollama, LM Studio, llama.cpp) — for natural language log querying and analysis.

Natural language filtering — press a and type plain English like "show me payment failures" or "find database timeouts in the last hour". The AI translates your query into lumolog's existing filters using actual log vocabulary.

Log analysis — narrow your logs with filters, then press A to send them to the AI with a question. Ask "what's causing these errors?", "any patterns here?", or "summarize what happened". The response appears in a scrollable overlay.

# Use with Ollama
lumolog --ai-provider=ollama app.log

# Use with LM Studio or any OpenAI-compatible server
lumolog --ai-provider=openai --ai-endpoint=http://127.0.0.1:1234/v1 --ai-model=your-model app.log

# Use with Claude API
ANTHROPIC_API_KEY=sk-... lumolog --ai-provider=claude app.log

When an AI backend is configured, an AI indicator appears in the status bar. Without configuration, the feature is completely invisible — lumolog works exactly as before.

Configuration via CLI flags or environment variables:

Setting	CLI Flag	Env Var
Provider	--ai-provider=claude|openai|ollama	LUMOLOG_AI_PROVIDER
Endpoint	--ai-endpoint=URL	LUMOLOG_AI_ENDPOINT
Model	--ai-model=NAME	LUMOLOG_AI_MODEL
API Key	—	ANTHROPIC_API_KEY / OPENAI_API_KEY

Command Palette

Press ? to open a fuzzy-searchable command palette showing every available action with its keybinding. Type to filter, arrow keys to select, Enter to execute.

Supported Formats

Lumolog auto-detects these formats by sampling the first lines of input:

Format	Example
JSON	{"level":"error","message":"failed","timestamp":"2024-01-15T10:30:00Z"}
Syslog	Jan 15 10:30:00 host sshd[1234]: Failed password for root
Logfmt	level=error msg="connection refused" host=api-1 duration=3.2s
klog (Kubernetes)	E0115 10:30:00.000000 1234 handler.go:42] error message
Log4j	2024-01-15 10:30:00 [main] ERROR com.app.Service - failed
Python logging	2024-01-15 10:30:00,123 - mymodule - ERROR - connection lost
Apache/Nginx	192.168.1.1 - - [15/Jan/2024:10:30:00 +0000] "GET /api" 500 1234
Plain text	Any text — level keywords and timestamps are still detected

Structured formats (JSON, logfmt, klog, Log4j, Python, Apache) extract level, timestamp, message, and extra fields into a compact [LVL] timestamp message key=value view. Extra fields are rendered dimmed after the message.

Pattern Highlighting

Lumolog recognizes and colorizes these inline patterns in all formats:

Pattern	Color	Example
URLs	Blue, underlined	https://api.example.com/v1/users
UUIDs	Magenta	550e8400-e29b-41d4-a716-446655440000
IPv4/IPv6	Cyan, bold	192.168.1.1, ::1
File paths	Green	/var/log/app.log, ./config/settings.toml
Pointer addresses	Orange	0x7fff5fbff8c0
Unix processes	Blue, bold	sshd[1234]
HTTP methods	Magenta, bold	GET, POST, DELETE
Key=value	Blue bold key	status=200, duration=3.2ms
Quoted strings	Gold	"connection refused"
Keywords	Red, italic	true, false, null, nil, NaN
Numbers	Cyan	42, 3.14, 500ms, 2.4GB
Dates	Gray	2024-01-15T10:30:00Z
Version numbers	Cyan	v2.4.1, 10.15.7

Patterns are matched in priority order — a URL won't have its path highlighted separately, and an IP inside a URL won't be double-colored.

Keybindings

Normal Mode

Key	Action
j / Down	Scroll down
k / Up	Scroll up
h / Left	Scroll left
l / Right	Scroll right
Space / PgDn	Page down
PgUp	Page up
g	Go to top
G	Go to bottom
/	Open filter bar
v	Level filter up (stricter)
V	Level filter down (looser)
p	Toggle JSON pretty-print
w	Toggle line wrap
t	Enter time range mode
Enter	Enter cursor mode
a	AI query (natural language filter)
A	AI analyze (send filtered logs to AI)
?	Open command palette
Esc	Clear active filter (similar > time > text)
q	Quit

Filter Mode

Key	Action
Type	Filter text (live results)
Backspace	Delete character
Enter	Accept filter and return to normal mode
Esc	Clear filter

Cursor Mode

Key	Action
j / Down	Move cursor down
k / Up	Move cursor up
y	Yank current line to clipboard
Y	Yank all filtered lines to clipboard
s	Filter by similar lines
Esc	Exit cursor mode

Time Range Mode

Key	Action
h / Left	Move cursor left
l / Right	Move cursor right
H / L	Move cursor left/right (fast)
[	Mark range start
] / Enter	Mark range end and apply
1	Last 5 minutes
2	Last 15 minutes
3	Last 1 hour
4	Last 24 hours
c	Clear time range
Esc	Exit time mode

AI Analysis Overlay

Key	Action
j / Down	Scroll down
k / Up	Scroll up
Space / PgDn	Page down
PgUp	Page up
Esc / q	Close overlay

Mouse

Action	Effect
Click token	Open context menu (filter, lookup, open)
Click stats bar badge	Set level filter
Click + drag sparkline	Select time range
Scroll wheel	Scroll vertically
Horizontal scroll	Scroll horizontally (supported terminals)

Requirements

• Rust 1.85+ (edition 2024)
• A modern terminal emulator (Ghostty, Kitty, WezTerm, iTerm2, Alacritty)
• Mouse support requires a terminal with SGR mouse encoding

License

MIT

---

Lumolog is under active development. Features and interfaces may change.