CLI Reference

Every flag the logpare CLI accepts, with real defaults, exit codes, and piping recipes.

Complete reference for the logpare command-line interface.

Installation

Install globally to use logpare from anywhere:

npm install -g logpare

Or use with npx for one-off usage:

npx logpare server.log

Basic Usage

logpare [options] [files...]
cat logs.txt | logpare [options]

There is no compress subcommand. logpare compress app.log is read as two file paths and fails with Error: File not found: compress. Pass options and paths directly.

With no file arguments, logpare reads stdin. With no file arguments and a TTY on stdin, it exits 1 with a usage hint. Multiple files are concatenated before compression, so templates are shared across them.

Compress a Single File

logpare server.log

Compress Multiple Files

logpare access.log error.log debug.log

Read from stdin

cat /var/log/syslog | logpare

tail -f app.log | logpare

journalctl -u myapp | logpare

Options

Output Format

`--format <format>` / `-f <format>`

Output format: summary, detailed, json, or json-stable

Default: summary

Examples:

# Summary format (default)
logpare server.log

# Detailed format with all metadata
logpare --format detailed server.log

# JSON format for programmatic processing
logpare --format json server.log

# Deterministic JSON (sorted keys, no whitespace) for diffing and prompt caching
logpare --format json-stable server.log

An unrecognised format is rejected with an error and exit code 1.

Output Destination

`--output <file>` / `-o <file>`

Write output to a file instead of stdout

Examples:

When --output is used, the compressed result goes to the file and a short Output written to <file> confirmation goes to stderr, keeping stdout clean.

# Write to file
logpare --output compressed.txt server.log

# JSON to file
logpare -f json -o result.json server.log

# Use with pipes
cat access.log | logpare -o summary.txt

Algorithm Parameters

`--depth <number>` / `-d <number>`

Parse tree depth. Any integer >= 1; values between 3 and 6 are the useful range in practice.

Default: 4

# Shallow depth for simple logs
logpare --depth 3 system.log

# Deep depth for complex logs
logpare --depth 6 application.log

`--threshold <number>` / `-t <number>`

Similarity threshold (0.0-1.0)

Default: 0.4

# More aggressive grouping
logpare --threshold 0.3 noisy.log

# More conservative grouping
logpare --threshold 0.5 structured.log

`--max-children <number>` / `-c <number>`

Maximum children per tree node

Default: 100

# Limit for memory efficiency
logpare --max-children 50 huge.log

`--max-clusters <number>` / `-m <number>`

Maximum total templates

Default: 1000

# Cap templates for large files
logpare --max-clusters 500 large.log

`--max-templates <number>` / `-n <number>`

Maximum templates in the output, in every format.

Default: 50

# Show only top 20 templates
logpare --max-templates 20 server.log

# Raise the cap rather than removing it
logpare --max-templates 1000 server.log

Must be a positive integer — 0 is rejected with exit code 1. There is no "show all" sentinel; pass a number at least as large as --max-clusters instead.

Help & Version

`--help` / `-h`

Show help message

logpare --help

`--version` / `-v`

Show version number

logpare --version

Examples

Basic Compression

# Compress a log file
logpare server.log

# Output:
# === Log Compression Summary ===
# Input: 10,847 lines → 23 templates (99.8% reduction)
#
# Top templates by frequency:
# 1. [4,521x] INFO Connection from <*> established
# 2. [3,892x] DEBUG Request <*> processed in <*>

Detailed Analysis

logpare --format detailed error.log

# Output:
# === Log Compression Details ===
# Input: 1,000 lines → 12 templates (98.8% reduction)
# Estimated token reduction: 96.3%
#
# === Template t001 (450 occurrences) ===
# Pattern: ERROR Connection to <*> failed
# Severity: error
# First seen: line 1
# Last seen: line 998
# URLs:
#   - https://api.example.com/v1/users
# Status codes: 500, 503
# Sample variables:
#   - 192.168.1.100
#   - 192.168.1.101

JSON Output

logpare --format json server.log > result.json

# Process with jq
logpare -f json server.log | jq '.templates[] | select(.severity == "error")'

# Pretty print
logpare -f json server.log | jq .

Piping from Other Commands

# Compress recent logs
tail -1000 /var/log/syslog | logpare

# Monitor live logs
tail -f app.log | logpare

# Compress journal logs
journalctl -u nginx | logpare -f detailed

# Kubernetes pod logs
kubectl logs my-pod | logpare

# Docker container logs
docker logs my-container | logpare

Parameter Tuning

# High compression (fewer templates)
logpare --depth 3 --threshold 0.3 noisy.log

# High fidelity (more templates)
logpare --depth 6 --threshold 0.5 structured.log

# Memory-efficient
logpare --max-clusters 500 --max-children 50 huge.log

Exit Codes

Code	Meaning
0	Success (also used by `--help` and `--version`)
1	Any error: invalid option value, unknown format, file not found, empty input

There is no distinct I/O exit code — every failure path exits 1.

Troubleshooting

"Command not found"

If you get logpare: command not found:

# Option 1: Use npx
npx logpare server.log

# Option 2: Install globally
npm install -g logpare

# Option 3: Use npm exec
npm exec logpare server.log

Large File Memory Issues

If processing fails with large files:

# Reduce memory usage
logpare --max-clusters 500 --max-children 50 huge.log

# Or process in chunks
head -100000 huge.log | logpare