Metadata-Version: 2.4
Name: logdelve
Version: 0.1.0
Summary: A CLI/TUI tool for viewing and filtering log lines
Author: Christian Assing
Author-email: Christian Assing <chris@ca-net.org>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Logging
Classifier: Topic :: Utilities
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.9
Requires-Dist: pydantic>=2.0
Requires-Dist: aiofiles>=24.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: boto3>=1.42.49 ; extra == 'aws'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/chassing/logdelve
Project-URL: Repository, https://github.com/chassing/logdelve
Project-URL: Issues, https://github.com/chassing/logdelve/issues
Provides-Extra: aws
Description-Content-Type: text/markdown

# logdelve

A terminal UI tool for viewing and filtering log lines. Think of it as a lightweight, interactive log viewer with JSON awareness.

## Features

- **File and pipe input**: Read logs from files or pipe them via stdin
- **Timestamp parsing**: Automatic detection of ISO 8601, syslog, Apache, and other common timestamp formats
- **JSON awareness**: Detects JSON content in log lines and offers pretty-printing with syntax highlighting
- **Pretty-print toggle**: Switch between compact and expanded JSON view, globally or per-line
- **Interactive filtering**: Filter log lines by text pattern or JSON key-value pairs (include or exclude)
- **Filter management**: Reorder, toggle, delete, clear filters with a dedicated dialog
- **Session management**: Save, load, rename, delete filter sessions with auto-save
- **Live tailing**: Follow growing log files in real-time with pause/resume
- **AWS CloudWatch**: Download and list CloudWatch log groups, streams, and events

## Installation

Requires Python 3.13+.

```bash
# Install with uv
uv tool install logdelve

# Or install with pip
pip install logdelve

# With AWS CloudWatch support
pip install logdelve[aws]
```

## Commands

### `logdelve inspect` - View log files

```bash
# View a log file (auto-tails by default)
logdelve inspect app.log

# Pipe logs from another command
kubectl logs pod-name | logdelve inspect

# Disable automatic tailing
logdelve inspect --no-tail app.log

# Load a saved filter session
logdelve inspect --session my-filters app.log
```

### `logdelve cloudwatch` - AWS CloudWatch logs

Requires `logdelve[aws]` (boto3).

```bash
# List log groups
logdelve cloudwatch groups
logdelve cloudwatch groups /aws/lambda/

# List streams for a log group
logdelve cloudwatch streams /aws/lambda/my-function

# Download recent logs (last 5 minutes by default)
logdelve cloudwatch get /aws/lambda/my-function stream-prefix

# Download with time range
logdelve cloudwatch get /aws/lambda/my-function prefix -s 1h -e 30m

# Download and view in TUI
logdelve cloudwatch get /aws/lambda/my-function prefix | logdelve inspect

# Tail CloudWatch logs live
logdelve cloudwatch get /aws/lambda/my-function prefix --tail | logdelve inspect
```

Time formats for `--start`/`--end`: `5m`, `1h`, `2d`, `1week`, `14:30`, or ISO 8601. All times in UTC.

AWS credentials via `--profile`, `--aws-region`, `--aws-access-key-id`, etc. or standard environment variables.

## Keybindings

### Navigation

| Key         | Action                    |
| ----------- | ------------------------- |
| Up / Down   | Move between log lines    |
| PgUp / PgDn | Page up / down            |
| Home / End  | Jump to first / last line |
| gg          | Jump to first line        |
| G           | Jump to last line         |

### JSON Display

| Key   | Action                                            |
| ----- | ------------------------------------------------- |
| j     | Toggle pretty-print for ALL JSON lines            |
| Enter | Toggle pretty-print for the current line (sticky) |
| n     | Toggle line numbers                               |

### Filtering

| Key | Action                                          |
| --- | ----------------------------------------------- |
| /   | Filter in (text or key=value)                   |
| \   | Filter out (text or key=value)                  |
| m   | Manage filters (toggle, delete, clear, reorder) |
| 1-9 | Toggle individual filters on/off                |

On JSON lines, `/` and `\` show key-value suggestions.

### Tailing

| Key | Action                            |
| --- | --------------------------------- |
| p   | Pause/resume tailing              |
| G   | Jump to bottom (follow new lines) |

### Sessions

| Key | Action                                              |
| --- | --------------------------------------------------- |
| s   | Session manager (load, save, delete, rename)        |

### General

| Key  | Action           |
| ---- | ---------------- |
| h, ? | Show help screen |
| q    | Quit             |

## Log Format

logdelve expects each line to begin with a timestamp, followed by either a JSON object or plain text:

```text
2024-01-15T10:30:00Z {"log_level": "info", "message": "Request processed", "duration_ms": 42}
2024-01-15T10:30:01Z Connection established from 192.168.1.1
Jan 15 10:30:02 myhost syslogd: restart
```

Lines without a recognized timestamp are displayed as-is.

## Sessions

Filter sessions are stored in `~/.config/logdelve/sessions/` as TOML files. Filters are auto-saved on every change. Use `--session` to load a session on startup.

## Development

```bash
# Clone the repo
git clone https://github.com/chassing/logdelve.git
cd logdelve

# Install dependencies
uv sync

# Run from source
uv run logdelve inspect sample.log

# Run all checks (lint, format, typecheck, tests)
make test

# Individual targets
make lint        # ruff check
make format      # ruff format
make typecheck   # mypy
make clean       # remove caches
```

## Releasing

1. Update version in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Commit and push: `git commit -am "Release vX.Y.Z" && git push`
4. Create a GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "See CHANGELOG.md"`
5. The `publish.yml` workflow builds and publishes to PyPI automatically

Requires `PYPI_TOKEN` secret in the GitHub repo settings.

## License

MIT
