logviewer

One CLI to query all your logs
Kubernetes • Docker • Splunk • OpenSearch • CloudWatch • SSH

Documentation • Issues • Discussions

---

LogViewer is a unified CLI tool for querying logs from multiple sources with consistent syntax. Stop juggling different tools and query languages—learn once, use everywhere.

Features

• Multi-source support — Query Kubernetes, Docker, Splunk, OpenSearch, CloudWatch, and SSH with one tool
• Unified query syntax — Same commands work across all backends
• Field extraction — Turn unstructured logs into searchable fields using regex
• Custom templates — Format output for humans or pipe to other tools
• Config-driven — Save complex queries as reusable contexts
• Multi-context search — Query multiple environments simultaneously
• Shell autocomplete — Tab completion for contexts, fields, and more
• AI integration — Use as an MCP server with Claude, Copilot, or Gemini
• High-performance filtering — Optional hl integration for fast local/SSH log processing

Quick Start

1. Install

Homebrew (macOS & Linux)

brew tap bascanada/tap
brew install logviewer

Scoop (Windows)

scoop bucket add bascanada https://github.com/bascanada/scoop-bucket
scoop install logviewer

Quick Install Script

curl -L "https://github.com/bascanada/logviewer/releases/latest/download/logviewer-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/')" -o ./logviewer && chmod +x ./logviewer
sudo mv ./logviewer /usr/local/bin/

See Installation for more options (Docker, AUR, build from source).

2. Configure

Run the interactive wizard:

logviewer configure

Or create ~/.logviewer/config.yaml manually:

clients:
  my-k8s:
    type: k8s

contexts:
  app-logs:
    client: my-k8s
    search:
      options:
        namespace: production
        pod: my-app-*

3. Query

# Query logs from your context
logviewer -i app-logs --last 10m query log

# Filter by fields
logviewer -i app-logs -f level=ERROR query log

# Discover available fields
logviewer -i app-logs query field

Use Cases

Debug across environments

# Query dev, staging, and prod simultaneously
logviewer -i app-dev -i app-staging -i app-prod --last 30m -f level=ERROR query log

Follow distributed transactions

# Filter by trace ID across services
logviewer -i api-gateway -i payment-service --last 1h -f traceId=abc-123 query log

Real-time monitoring

# Tail logs with auto-refresh
logviewer -i app-logs --refresh 2s query log

Custom output formatting

# Use Go templates
logviewer -i app-logs --format "[{{.Timestamp.Format \"15:04:05\"}}] {{.Level}}: {{.Message}}" query log

AI-powered investigation

# Start MCP server for AI agents
logviewer mcp --config ~/.logviewer/config.yaml

Then ask Claude, Copilot, or Gemini: "Find all payment errors in the last hour"

Supported Backends

Backend	Type	Native Query	Notes
Kubernetes	k8s	—
Docker	docker	—
Local/SSH	local, ssh	—	hl support for fast filtering
OpenSearch/Elasticsearch	opensearch	Lucene
Splunk	splunk	SPL
AWS CloudWatch	cloudwatch	Insights

Documentation

Full documentation is available in the GitHub Wiki:

Getting Started

• Installation — All installation methods
• CLI Usage — Command reference
• Configuration — Config file setup

Features

• Field Extraction — Parse structured data from logs
• Templates — Custom output formatting
• Variables — Dynamic context parameters
• Multi-Context Search — Query multiple sources

Backends

• Backends Reference — K8s, Docker, Splunk, OpenSearch, CloudWatch, SSH
• HL Integration — High-performance filtering with hl

AI Integration

• MCP Integration — Setup for AI agents
• LLM Usage Guide — Best practices for AI

Help

• Troubleshooting — Common issues
• FAQ — Frequently asked questions

Example Configuration

clients:
  prod-splunk:
    type: splunk
    options:
      url: https://splunk.example.com:8089
      token: ${SPLUNK_TOKEN}

  prod-k8s:
    type: k8s
    options:
      kubeConfig: ~/.kube/prod-config

searches:
  json-format:
    fieldExtraction:
      json: true
    printerOptions:
      template: '[{{.Timestamp.Format "15:04:05"}}] {{.Level}} {{.Message}}'

contexts:
  payment-logs:
    description: "Payment service logs in Splunk"
    client: prod-splunk
    searchInherit: ["json-format"]
    search:
      options:
        index: payment-service
        timestampFormat: "2006-01-02 15:04:05" # Optional: custom timestamp format

  api-gateway:
    description: "API Gateway pods in Kubernetes"
    client: prod-k8s
    search:
      options:
        namespace: production
        pod: api-gateway-*

Contributing

Contributions are welcome! Please:

• Report bugs via GitHub Issues
• Request features via GitHub Issues
• Ask questions in GitHub Discussions
• Submit PRs for bug fixes or new features

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

---

_{Made with ❤️ for DevOps engineers tired of juggling log tools}