watchr

watchr is a terminal UI for running commands and interactively browsing their output. It provides vim-style navigation, filtering, and a preview pane—all without leaving your terminal.

---

🚀 Features

• Interactive output viewer: Browse command output with vim-style keybindings
• Live filtering: Press / to filter output lines in real-time, with regex support (//)
• Preview pane: Toggle a resizable preview panel (bottom, top, left, or right) with JSON syntax highlighting
• Auto-refresh: Optionally re-run commands at specified intervals
• Line numbers: Optional line numbering with configurable width
• Config files: YAML, TOML, or JSON config files for persistent settings
• Full-screen TUI: Clean, distraction-free interface using your entire terminal

---

🎯 Installation

Download Precompiled Binaries

Grab the latest release for Linux, macOS, or Windows:

• Releases →

Homebrew (macOS/Linux)

Install directly from the tap:

brew install chenasraf/tap/watchr

Or tap and then install the package:

brew tap chenasraf/tap
brew install watchr

From Source

git clone https://github.com/chenasraf/watchr
cd watchr
make build
make install  # installs to ~/.local/bin

---

✨ Getting Started

Basic Usage

# View output of any command
watchr ls -la

# View logs
watchr "tail -100 /var/log/system.log"

# Monitor processes
watchr "ps aux"

Auto-Refresh

# Refresh every 2 seconds
watchr -r 2 "docker ps"

# Refresh every 500 milliseconds
watchr -r 500ms "date"

# Refresh every 1.5 seconds
watchr -r 1.5s "kubectl get pods"

# Refresh every 5 minutes
watchr -r 5m "df -h"

# Refresh every hour
watchr -r 1h "curl -s https://api.example.com/status"

# Watch file changes
watchr -r 5 "find . -name '*.go' -mmin -1"

Options

Usage: watchr [options] <command to run>

Options:
  -c, --config string             Load config from specified path
  -h, --help                      Show help
  -i, --interactive               Run shell in interactive mode (sources ~/.bashrc, ~/.zshrc, etc.)
  -w, --line-width int            Line number width (default 6)
  -n, --no-line-numbers           Disable line numbers
  -o, --preview-position string   Preview position: bottom, top, left, right (default "bottom")
  -P, --preview-size string       Preview size: number for lines/cols, or number% for percentage (e.g., 10 or 40%) (default "40%")
  -p, --prompt string             Prompt string (default "watchr> ")
  -r, --refresh string            Auto-refresh interval (e.g., 1, 1.5, 500ms, 2s, 5m, 1h; default unit: seconds, 0 = disabled) (default "0")
      --refresh-from-start        Start refresh timer when command starts (default: when command ends)
  -s, --shell string              Shell to use for executing commands (default "sh")
  -C, --show-config               Show loaded configuration and exit
  -v, --version                   Show version

---

📁 Configuration File

watchr supports configuration files in YAML, TOML, or JSON format. Settings in config files serve as defaults that can be overridden by command-line flags.

Config File Locations

Config files are searched in the following order (later files override earlier ones):

1. XDG config directory (Linux/macOS): ~/.config/watchr/watchr.{yaml,toml,json}
2. Windows: %APPDATA%\watchr\watchr.{yaml,toml,json}
3. Current directory (project-local): ./watchr.{yaml,toml,json}

Example Configurations

YAML (watchr.yaml):

shell: bash
preview-size: '50%'
preview-position: right
line-numbers: true
line-width: 4
prompt: '> '
refresh: 0 # disabled; or use: 2, 1.5, "500ms", "2s", "5m", "1h"
interactive: false

TOML (watchr.toml):

shell = "bash"
preview-size = "50%"
preview-position = "right"
line-numbers = true
line-width = 4
prompt = "> "
refresh = 0 # disabled; or use: 2, 1.5, "500ms", "2s", "5m", "1h"
interactive = false

JSON (watchr.json):

{
  "shell": "bash",
  "preview-size": "50%",
  "preview-position": "right",
  "line-numbers": true,
  "line-width": 4,
  "prompt": "> ",
  "refresh": 0,
  "interactive": false
}

The refresh option accepts:

• Numbers: 2 or 1.5 (interpreted as seconds)
• Explicit units: "500ms", "2s", "5m", "1h"

Priority Order

Configuration values are applied in this order (later sources override earlier ones):

1. Built-in defaults
2. XDG/system config file
3. Project-local config file (current directory)
4. Command-line flags

---

⌨️ Keybindings

Key	Action
r, Ctrl-r	Reload (re-run command)
R	Reload & clear all lines
d, Del	Delete selected line
D	Clear all lines
c	Stop running command
q, Esc	Quit
j, k	Move down/up
g	Go to first line
G	Go to last line
Ctrl-d, Ctrl-u	Half page down/up
PgDn, Ctrl-f	Full page down
PgUp, Ctrl-b	Full page up
p	Toggle preview pane
+ / -	Increase / decrease preview size
J / K	Scroll preview down / up
/	Enter filter mode
//	Toggle regex filter mode
Esc	Exit filter mode / clear filter
y	Yank (copy) selected line
Y	Yank selected line (plain text)
:	Open command palette
?	Show help overlay

Filter mode

When in filter mode (/), the following keys are available:

Key	Action
Enter	Confirm filter
Esc	Cancel and clear filter
Left / Right	Move cursor within filter
Alt-Left / Alt-Right	Move cursor by word
Backspace	Delete character before cursor
Alt-Backspace	Delete word before cursor
/	Toggle regex mode (when filter is empty)

---

🛠️ Contributing

I am developing this package on my free time, so any support, whether code, issues, or just stars is very helpful to sustaining its life. If you are feeling incredibly generous and would like to donate just a small amount to help sustain this project, I would be very very thankful!

I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature, don’t hesitate to open an appropriate issue and I will do my best to reply promptly.

---

📜 License

watchr is licensed under the MIT License.