grafatui-0.1.4 is not a library.

Grafatui

Grafatui is a terminal-based user interface (TUI) for Prometheus, inspired by Grafana. It allows you to visualize time-series data directly in your terminal with a lightweight, keyboard-driven interface.

Why Grafatui?

🚀 Lightweight: No browser, no Electron, just your terminal
⚡ Fast: Sub-second startup, minimal resource usage
📊 Familiar: Import your existing Grafana dashboards
⌨️ Keyboard-first: Navigate and explore without touching your mouse
🎨 Customizable: Multiple themes and configuration options

Quick Start

If you already have Prometheus running:

# Install from crates.io
cargo install grafatui

# Run with your Prometheus instance
grafatui --prometheus-url http://localhost:9090

Or try the included demo with zero setup:

git clone https://github.com/fedexist/grafatui.git
cd grafatui
cd examples/demo && docker-compose up -d && sleep 5 && cd ../..
cargo run -- --grafana-json examples/dashboards/prometheus_demo.json --prometheus-url http://localhost:19090

This demo showcases all 7 visualization types (graph, stat, gauge, bar gauge, table, heatmap) using a local Prometheus instance.

Features

Prometheus Integration

Direct connection to any Prometheus instance
Real-time updates with configurable refresh rates
Optimized queries with caching and request deduplication

Grafana Dashboard Import

Import existing dashboards from JSON files
Supported panels: graph, timeseries, gauge, bargauge, table, stat, heatmap
Template variables with CLI overrides
Legend formatting ({{label}} syntax)
Grid layouts using gridPos

Interactive TUI

Time controls: Zoom, pan, and jump to live updates
Panel navigation: Arrow keys, vim-style, or mouse
Search: Quickly find panels by name
Fullscreen mode: Focus on a single panel
Value inspection: Cursor-based point-in-time data exploration
Series toggling: Show/hide individual metrics

Customization

8 themes: default, dracula, monokai, solarized (dark/light), gruvbox, tokyo-night, catppuccin
Config file support (TOML)
Flexible CLI with sensible defaults

Installation

From Crates.io

cargo install grafatui

From Source

Ensure you have Rust installed (1.85+ recommended).

git clone https://github.com/fedexist/grafatui.git
cd grafatui
cargo install --path .

Prebuilt Binaries

Download the latest release for your platform from GitHub Releases:

Linux (x86_64, aarch64)
macOS (x86_64, aarch64)
Windows (x86_64)

Package Managers

Homebrew (coming soon):

brew install grafatui

Shell Completions

Grafatui can generate shell completions for Bash, Zsh, Fish, PowerShell, and Elvish.

Bash:

# Add to .bashrc
source <(grafatui completions bash)

Zsh:

# Add to .zshrc
source <(grafatui completions zsh)

Fish:

grafatui completions fish | source

Usage

grafatui [OPTIONS]

Common Options

Option	Description	Default
`--prometheus-url <URL>`	Prometheus server URL	`http://localhost:9090`
`--grafana-json <FILE>`	Import Grafana dashboard JSON	-
`--range <DURATION>`	Time range window (e.g., `5m`, `1h`, `24h`)	`5m`
`--step <DURATION>`	Query step resolution (e.g., `5s`, `30s`)	`5s`
`--var <KEY=VALUE>`	Override dashboard variables	-
`--theme <NAME>`	UI theme	`default`
`--refresh-rate <MS>`	Data fetch interval (milliseconds)	`1000`
`--config <FILE>`	Custom config file path	-

Run grafatui --help for the full list of options.

Configuration File

Create a grafatui.toml in ~/.config/grafatui/ (or use --config):

prometheus_url = "http://localhost:9090"
refresh_rate = 1000
time_range = "1h"
theme = "dracula"
grafana_json = "~/.config/grafatui/my-dashboard.json"

Examples

Basic usage:

grafatui --prometheus-url http://localhost:9090

Import a Grafana dashboard:

grafatui --prometheus-url http://prod-prom:9090 --grafana-json ./node-exporter.json

Override template variables:

grafatui --grafana-json ./dash.json --var job=node --var instance=server-01

Use a theme:

grafatui --theme tokyo-night

Try the included examples:

# All visualization types
grafatui --grafana-json examples/dashboards/all_visualizations.json --prometheus-url http://localhost:9090

# vLLM monitoring (mock demo)
cd examples/demo && docker-compose up -d && cd ../..
grafatui --config examples/demo/grafatui.toml

Tip: See the examples/ directory for more sample dashboards.

Keyboard Controls

Key	Action
`q`	Quit
`r`	Force refresh
`+` / `-`	Zoom out / in
`[` / `]`	Pan left / right (time)
`0`	Reset to live mode
`↑` / `↓` or `k` / `j`	Select previous/next panel
`PgUp` / `PgDn`	Scroll vertically
`Home` / `End`	Jump to top / bottom
`y`	Toggle Y-axis mode
`1`..`9`	Toggle series visibility
`f` / `Enter`	Fullscreen mode
`v`	Value inspection mode
`/`	Search panels
`←` / `→`	Move cursor (inspect mode)
`?`	Toggle debug info

Mouse Support

Click: Select panel (or move cursor in fullscreen inspect mode)
Drag: Move cursor (fullscreen inspect mode only)
Scroll: Scroll dashboard vertically

Note: In normal mode, clicking selects panels. Press v or f to enable cursor interaction.

Comparison with Grafana

Feature	Grafatui	Grafana
Resource usage	~10 MB RAM	~500+ MB RAM
Startup time	<1 second	5-10 seconds
Interface	Terminal (TUI)	Web browser
Dashboard format	Import Grafana JSON	Native
Ideal for	Quick debugging, SSH sessions, minimal environments	Production monitoring, complex dashboards, sharing

Use Grafatui when:

You're SSH'd into a server and want quick metrics
You need fast, low-overhead monitoring
You live in the terminal
You want keyboard-first workflow

Use Grafana when:

You need advanced features (alerts, annotations, user management)
You're building dashboards for a team
You need rich visualizations and plugins

Performance

Grafatui is designed to be fast and resource-efficient:

Minimal footprint: ~10 MB memory usage
Smart caching: Deduplicates identical queries across panels
Client-side downsampling: Adapts data points to terminal width
Async architecture: Non-blocking UI using Tokio

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick tips:

Use Conventional Commits for your commit messages
Run cargo fmt and cargo clippy before submitting
Add tests for new features

Acknowledgments

Grafatui is built with amazing open-source libraries:

ratatui - Terminal UI framework
crossterm - Terminal manipulation
tokio - Async runtime
reqwest - HTTP client

Inspired by Grafana and the TUI ecosystem.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

grafatui 0.1.4