kentrawatch 0.1.0

A beautiful TUI replacement for `watch` with graphs, stats, and multiple views

kentraWATCH

A beautiful TUI replacement for watch with live graphs, stats dashboards, and structured output parsing.

Features

• Live command execution — run any command at a configurable interval (0.5s–60s)
• Output view — colored diff with fade-away change highlighting, word wrap toggle, horizontal scroll
• Graph view — auto-detected numeric columns plotted as line charts over time
• Stats view — timing, history, uptime, and exit code dashboard
• Structured output parsing — auto-detects delimiters (comma, tab, pipe, semicolon, whitespace) and numeric columns with unit suffix parsing (K, M, G, T, P)
• Settings modal — categorized two-pane settings screen for all options
• Config persistence — ~/.kentrawatch/config.json auto-saves on every change
• Themes — toggle between 21+ Textual themes
• Pause/resume — freeze execution without losing history
• Maximize mode — hide chrome for a focused view (m)
• File logging — ~/.kentrawatch/kentrawatch.log with rotation

Installation

pip install kentrawatch

Or from source:

git clone https://github.com/yourusername/kentrawatch
cd kentrawatch
pip install -e .

Requires Python ≥3.12.

Usage

kentrawatch [options] <command>
kw [options] <command>

Examples

# Watch disk usage
kentrawatch "df -h"

# Watch with custom interval and CSV parsing
kentrawatch -n 5 -d , "ps aux | awk '{print \$3,\$4}'"

# Disable change highlighting
kentrawatch --no-highlight "vm_stat"

# Set log level
kentrawatch --log-level DEBUG "ping -c 1 8.8.8.8"

Options

Flag	Default	Description
-n, --interval	2.0	Update interval in seconds (min 0.5)
-d, --delimiter	auto	Column delimiter for structured output
--history	100	Number of runs to keep in history
--log-level	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
--version	—	Show version and exit
--highlight / --no-highlight	on	Enable/disable change highlighting

Keybindings

Key	Action
q	Quit
r	Reset history
p	Pause/resume
w	Toggle word wrap
s	Open settings modal
m	Toggle maximize mode
+ / -	Increase/decrease interval by 0.5s

Views

The interface has three tabs, navigable by clicking:

Tab	Content
Output	Command stdout with diff highlighting and fade animation
Graphs	Live line charts for numeric columns across runs
Stats	Timing, command, history, and exit code dashboard

Settings Modal

Press s to open the categorized settings modal:

Category	Settings
Display	Theme (21+ Textual themes), Highlight toggle, Word Wrap toggle
Execution	Interval, Delimiter, History Size
Logging	Log Level (DEBUG–CRITICAL)

All changes apply immediately and persist to ~/.kentrawatch/config.json.

Configuration

Settings are saved to ~/.kentrawatch/config.json:

{
  "interval": 2.0,
  "delimiter": null,
  "history_size": 100,
  "theme": "dracula",
  "highlight": true,
  "wrap": true,
  "log_level": "INFO"
}

CLI flags override config file values.

Logging

Logs are written to ~/.kentrawatch/kentrawatch.log with automatic rotation at 10 MB (3 backups retained).

Dependencies

• Textual — TUI framework
• textual-plotext — terminal plotting
• Rich — styled output
• typed-argument-parser — CLI args
• Loguru — logging