# Sampler — Real-Time Terminal Dashboards from Shell Commands

> Sampler is a tool for shell commands execution, visualization, and alerting, turning any CLI output into live-updating terminal charts and gauges.

## Install

Save as a script file and run:

# Sampler — Real-Time Terminal Dashboards from Shell Commands

## Quick Use
```bash
brew install sampler
sampler -c config.yml
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-00d6522a
Author: Script Depot