npm package: @redredchen01/log-parser
Description: CLI toolkit for log analysis — filter, tail, stats, JSON parsing, highlighting, extraction
Latest version: 1.0.0

# @foundry/log-parser

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

[![npm version](https://img.shields.io/npm/v/@foundry/log-parser.svg)](https://www.npmjs.com/package/@foundry/log-parser)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

### CLI Tool

```bash
npm install -g @foundry/log-parser
```

### Claude Code Skill

Download `.skill` file from [GitHub Releases](https://github.com/redredchen01/skill-foundry/releases):

```bash
claude skill install log-parser.skill
```

## Quick Start

```bash
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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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