@foundry/log-parser

CLI toolkit for log analysis — filter, tail, stats, JSON parsing, highlighting, extraction

Install

CLI Tool

npm install -g @foundry/log-parser

Claude Code Skill

Download .skill file from GitHub Releases:

claude skill install log-parser.skill

Quick Start

log-parser --help

Commands

| Command | Description | |-------------|-----------------------------------------------------------| | filter | Filter log lines by pattern, level, or time range | | tail | Follow log files with color highlighting | | stats | Aggregate log statistics (error counts, frequency) | | json | Parse and query JSON-formatted logs (NDJSON) | | highlight | Add color highlighting to log output (pipe-friendly) | | extract | Extract structured data (IPs, URLs, emails, timestamps) |

Usage Examples

filter — find lines by level, pattern, or time

# Show only errors
log-parser filter --level ERROR app.log

# Filter by regex pattern
log-parser filter --pattern "timeout|refused" app.log

# Exclude matching lines
log-parser filter --pattern "healthcheck" --invert app.log

# Time range
log-parser filter --since "2024-01-01 10:00:00" --until "2024-01-01 11:00:00" app.log

# Pipe from stdin
cat app.log | log-parser filter --level WARN

tail — follow a file with live color highlighting

log-parser tail --file /var/log/app.log
log-parser tail --file app.log -n 50
log-parser tail --file app.log --level ERROR
log-parser tail --file app.log --pattern "user_id=42"

stats — aggregated counts and distributions

# Level breakdown + error rate
log-parser stats app.log

# Top 10 most frequent (normalized) messages
log-parser stats --group-by message app.log

# Lines per hour
log-parser stats --group-by hour app.log

# Top 20
log-parser stats --top 20 --group-by message app.log

json — query NDJSON / structured logs

# Pretty-print all entries
log-parser json app.log

# Filter entries where level=error
log-parser json --where 'level=error' app.log

# Extract a single field
log-parser json --field message app.log

# Table view
log-parser json --format table app.log

# Pipe-friendly
cat app.log | log-parser json --where 'status=500' --format compact

highlight — colorize log output

# Auto-color by level (pipe-friendly)
cat app.log | log-parser highlight

# Highlight extra pattern in cyan
cat app.log | log-parser highlight --pattern "timeout"

# Custom color
cat app.log | log-parser highlight --pattern "user_id=\d+" --color magenta

extract — pull out structured values

# Extract all IP addresses
log-parser extract --type ip access.log

# Unique URLs
log-parser extract --type url --unique app.log

# Count error messages
log-parser extract --type error --count app.log

# Extract timestamps
log-parser extract --type timestamp app.log

# All types at once
cat app.log | log-parser extract --unique

As Claude Skill

After installing, describe what you want in natural language. For example:

"Parse the log file and show me all errors from the last hour" "How many warnings are in app.log? Group by message" "Tail the nginx access log and highlight 500 errors" "Extract all IPs from access.log and count them" "Filter the JSON logs where status=500"

Requirements

• bash 3.2+
• node (required only for the json command)

License

MIT