# Kelora
**Turn messy logs into structured data.**
Kelora is a scriptable log processor for the command line. Parse mixed formats, filter with complex logic, and analyze streams using embedded [Rhai](https://rhai.rs) scripting—all in a single binary.
```bash
cargo install kelora
```
> Or download pre-built binaries for **Windows, macOS, and Linux** from [GitHub Releases](https://github.com/dloss/kelora/releases).
!!! note "Development Status"
Pre-1.0 tool generated entirely by AI agents. Validated by a large test suite and Rust security tools; see [Development Approach](#development-approach) and the [Security Policy](https://github.com/dloss/kelora/blob/main/SECURITY.md) before relying on it in production. APIs might change without notice before v1.0.
## When to Use Kelora
Kelora trades speed for programmability. It's slower than grep, awk, and jq, but adds stateful scripting for complex multi-stage transformations.
**Reach for Kelora when:**
- You have **mixed formats** - Logs that aren't consistently JSON or need custom parsing
- You're **chaining tools** - Replacing `grep | awk | jq | custom-script.py` with one command
- You need **stateful logic** - Counting errors per service, windowed metrics, lookup tables
- You want **embedded scripting** - Complex transformations without leaving your shell
**Use specialized tools for:**
- **Fast search**: `grep`/`rg` (50-100× faster) - Finding text patterns in logs
- **Simple splitting**: `awk` (faster, ubiquitous) - Field extraction and simple statistics
- **JSON queries**: `jq` (faster, everywhere) - Querying structured JSON documents
- **Interactive exploration**: `lnav` (TUI with SQL) - Browsing logs with a visual interface
Kelora reads from files or stdin and outputs JSON, CSV, or Logfmt. Combine it with [lnav, jq, qsv, and other tools](how-to/integrate-external-tools.md) for visualization, analytics, and storage.
---
## Live Examples
### 1. Filter & Convert (The Basics)
*Scenario: Filter a Logfmt file for slow requests and output clean JSON.*
=== "Command/Output"
```bash exec="on" source="above" result="ansi"
kelora -f logfmt examples/traffic_logfmt.log \
--filter 'e.status.to_int() >= 500 || e.latency_ms.to_int() > 1000' \
-F json
```
=== "Input Data"
```bash exec="on" result="ansi"
cat examples/traffic_logfmt.log
```
### 2. Modify & Anonymize (Scripting)
*Scenario: Mask user emails for privacy and convert milliseconds to seconds before printing.*
=== "Command/Output"
```bash exec="on" source="above" result="ansi"
kelora -j examples/audit.jsonl \
--exec 'e.email = "***"; e.duration_sec = e.ms / 1000.0;' \
--keys timestamp,user_id,email,duration_sec
```
=== "Input Data"
```bash exec="on" result="ansi"
cat examples/audit.jsonl
```
### 3. Contextual Analysis (Pipeline Order)
*Scenario: An error occurred. We want to see the error, but enrich it with context from the **previous** log line (even if that line wasn't an error).*
!!! tip "Sequential Pipeline"
Kelora processes flags in order. We run `--exec` **before** `--filter` so the sliding window can see the normal events before they are discarded.
=== "Command/Output"
```bash exec="on" source="above" result="ansi"
kelora -j examples/api_errors.jsonl \
--window 2 \
--exec 'if e.level == "ERROR" && window.len() > 1 {
e.prev_ctx = window[1].info;
}' \
--filter 'e.level == "ERROR"' \
-F logfmt
```
=== "Input Data"
```bash exec="on" result="ansi"
cat examples/api_errors.jsonl
```
---
## Advanced Features
Beyond basic filtering and conversion, Kelora includes specialized functions that solve problems you'd otherwise need multiple tools or custom scripts for:
- **[Deep flattening](how-to/power-user-techniques.md#deep-structure-flattening)** - Fan out nested JSON arrays to flat records (`emit_each()`)
- **[Extract JSON from text](how-to/power-user-techniques.md#extract-json-from-unstructured-text)** - Pull structured data from unstructured log lines
- **[JWT parsing](how-to/power-user-techniques.md#jwt-parsing-without-verification)** - Extract claims without signature verification for debugging
- **[Cryptographic pseudonymization](how-to/power-user-techniques.md#multiple-hash-algorithms)** - Privacy-preserving anonymization with Argon2id + HKDF + HMAC
- **[Pattern normalization](how-to/power-user-techniques.md#pattern-normalization)** - Group error messages by replacing IPs, UUIDs, emails with placeholders
- **[Deterministic sampling](how-to/power-user-techniques.md#deterministic-sampling-with-bucket)** - Hash-based sampling that's consistent across log rotations and distributed systems
See **[Power-User Techniques](how-to/power-user-techniques.md)** for real-world examples. For performance characteristics and when to use specialized tools instead, see [Performance Comparisons](concepts/performance-comparisons.md).
---
## Get Started
**[→ Quickstart (5 minutes)](quickstart.md)** - Install and run your first commands
**[→ Tutorial: Basics (30 minutes)](tutorials/basics.md)** - Learn input formats, filtering, and output
**[→ Troubleshooting](troubleshooting.md)** - Fix common issues and debug effectively
**[→ How-To Guides](how-to/index.md)** - Solve specific problems
For deeper understanding, see [Concepts](concepts/index.md). For complete reference, see [Glossary](glossary.md), [Functions](reference/functions.md), [Formats](reference/formats.md), and [CLI options](reference/cli-reference.md).
---
## License
Kelora is open source software licensed under the [MIT License](https://github.com/dloss/kelora/blob/main/LICENSE).
## Development Approach
Kelora is an experiment in agentic AI development. Claude Code (Sonnet 4.5) and Codex CLI (gpt-5-codex) generate all implementation and tests; I steer requirements but do not write or review code. Validation relies on the automated test suite plus `cargo audit` and `cargo deny`, so please inspect the code yourself before relying on it in production and expect the API to evolve until 1.0. This is a spare-time, single-developer project, so support and updates are best-effort.
