LogScope

Beautiful, simple, and powerful log viewer for the terminal.

A modern CLI tool that turns boring text logs or messy JSON lines into stunning, structured, and colorful terminal outputs—complete with a live dashboard, smart highlighting, and HTML exporting.

---

Features that shine

• Fast & Lightweight: Tail files natively or stream huge data directly via pipes (cat server.log | logscope).
• Colored & Structured Logs: Automatically identifies INFO, WARNING, ERROR, CRITICAL, and DEBUG, applying beautiful typography.
• Universal Parser: Reads typical bracket logs ([INFO]) and parses modern NDJSON / JSON logs out of the box (e.g., Kubernetes, Docker).
• Auto-Highlighting: Magically highlights IPs, URLs, Dates/Timestamps, UUIDs, and E-Mails with dynamic colors.
• Custom Keyword Highlighting: Highlight specific keywords in log messages with --highlight and customize colors with --highlight-color.
• Live Dashboard: Watch logs stream in real-time alongside a live statistics panel keeping track of Error vs Info counts (--dashboard).
• HTML Export: Loved your console output so much you want to share it? Export the beautiful log structure directly to an HTML file to share with your team! (--export-html results.html)
• Filtering: Filter by one or more levels (--level ERROR or --level ERROR,WARN,INFO). Search by substring (--search) or regular expression (--regex / -e), with optional case-sensitive matching and invert match (--invert-match / -v, grep-style) to hide matching lines.
• Themes: Choose from 6 beautiful themes (default, neon, ocean, forest, minimal, spectra) or create custom themes via config file.
• Plain output: Use --no-color when you need unstyled text (e.g. piping to other tools or logs without ANSI codes).
• Gzip logs: Read .gz files directly—LogScope opens them as text without a manual zcat pipe.

---

Installation

Ensure you have Python 3.9+ and pip installed.

# Clone the repository
git clone https://github.com/vinnytherobot/logscope.git
cd logscope

# Install via Poetry
poetry install
poetry run logscope --help

# Or install globally via pip
pip install -e .

---

Usage & Examples

Using a File

# Basic colorized look
logscope /var/log/syslog

# Tailing a log in real-time (like tail -f)
logscope backend.log --follow

# Filter only errors
logscope production.log --level ERROR

# Multiple levels (comma-separated)
logscope production.log --level ERROR,WARN,INFO

# Search text dynamically
logscope server.log --search "Connection Timeout"

# Regex search (requires --search)
logscope server.log --search "timeout|refused|ECONNRESET" --regex

# Hide lines that match a pattern
logscope noisy.log --search "healthcheck" --invert-match

# Case-sensitive search
logscope app.log --search "UserID" --case-sensitive

# Highlight specific keywords
logscope server.log --highlight "timeout" --highlight-color "bold red"

# No colors (plain terminal output)
logscope app.log --no-color

# Compressed log file
logscope archive/app.log.gz

Piping from other commands (Stdin support)

LogScope acts as a brilliant text reformatter for other tools!

kubectl logs my-pod -f | logscope
docker logs api-gateway | logscope --level CRITICAL
cat nginx.log | grep -v GET | logscope --dashboard

The Live Dashboard Mode

Monitor your logs like a pro with a live dashboard tracking error occurrences.

logscope app.log --dashboard --follow

Exporting to HTML

Need to attach the logs to a Jira ticket or Slack message but want to keep the formatting?

logscope failed_job.log --export-html bug_report.html

Themes

Choose from 6 beautiful themes: default, neon, ocean, forest, minimal, spectra.

logscope app.log --theme neon

Create a .logscoperc file to set your preferred theme:

{
  "theme": "neon",
  "custom_themes": {
    "my-theme": {
      "levels": {
        "ERROR": ("✖", "bold red")
      }
    }
  }
}

---

Stack

• Rich -> UI Layouts, Colors, Highlighters, HTML Export.
• Typer -> Modern, fast, and robust CLI creation.
• typing-extensions -> Typed CLI annotations on Python 3.9.
• Pathlib / Sys / gzip -> File and standard input streaming; gzip text logs.

Contributing

Open an issue or submit a pull request! Tests are written using pytest.

# Running tests
pytest tests/

License

MIT License.

Made by vinnytherobot