Sampler — Real-Time Terminal Dashboards from Shell Commands

Introduction

Sampler lets you define shell commands in a YAML file and visualize their output as live-updating charts, gauges, sparklines, and text panels in the terminal. It turns any CLI one-liner into a monitoring dashboard without writing code.

What Sampler Does

• Executes shell commands on a configurable schedule and renders the output as terminal widgets
• Supports line charts, bar charts, sparklines, gauges, and plain text boxes
• Triggers alerts via terminal bell or custom scripts when values cross thresholds
• Runs multiple data sources concurrently with independent refresh rates
• Reads all configuration from a single YAML file

Architecture Overview

Sampler is a single Go binary that parses a YAML config describing data sources and their visualization types. Each data source spawns a goroutine that periodically executes a shell command and feeds the output to a rendering component built on the termui library. The layout engine arranges widgets on a grid, and an alert subsystem watches values against user-defined thresholds.

Self-Hosting & Configuration

• Install via Homebrew, Scoop, or download the binary from GitHub Releases
• Create a config.yml that defines runcharts, barcharts, sparklines, gauges, or textboxes
• Each widget specifies a sample shell command and a rate-ms refresh interval
• Set triggers to fire alerts when a metric exceeds a threshold
• Launch with sampler -c config.yml; use environment variables for secrets

Key Features

• Zero dependencies beyond a shell — any command that prints a number or text can be a data source
• Visually rich terminal UI with color-coded charts and smooth scrolling
• Built-in alert system with threshold triggers and custom notification scripts
• Lightweight single binary, under 10 MB
• Works over SSH for remote server monitoring

Comparison with Similar Tools

• WTF (wtfutil) — integrates with specific third-party APIs; Sampler visualizes arbitrary shell command output
• Grafana — web-based dashboards with persistent storage; Sampler is ephemeral and terminal-only
• watch — re-runs a single command; Sampler runs many commands and renders them as charts
• Glances — monitors system metrics specifically; Sampler can monitor anything a shell command can query

FAQ

Q: Do I need a database to store metrics? A: No. Sampler is stateless and re-samples on every interval. For persistent data, pipe to a TSDB.

Q: Can I monitor remote servers? A: Yes. Use SSH commands in your sample definitions, or run Sampler directly over an SSH session.

Q: What shells are supported? A: Sampler uses the system default shell. Bash, Zsh, and Fish all work.

Q: Can I export the dashboard as an image? A: There is no built-in export, but you can use terminal recording tools like asciinema or VHS.

Sources

• https://github.com/sqshq/sampler
• https://sampler.dev