Grafatui

Grafatui is a terminal user interface for Prometheus, inspired by Grafana. It lets you inspect time-series dashboards from a fast, keyboard-driven TUI that works well over SSH and in minimal environments.

Quick Start

Install with Homebrew on macOS or Linux:

brew install fedexist/grafatui/grafatui

Or install the latest prebuilt binary:

bash -o pipefail -c 'curl --proto =https --tlsv1.2 -LsSf https://raw.githubusercontent.com/fedexist/grafatui/main/install.sh | bash'

Or install from crates.io:

cargo install grafatui

Run against a Prometheus instance:

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

Or try the included demo:

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

Features

• Prometheus range and instant queries with async fetching.
• Bounded Prometheus responses, retry classification, range-query deduplication, and a bounded result cache.
• Grafana Classic JSON and V2 Resource JSON/YAML import for graph, timeseries, stat, gauge, bar gauge, table, and heatmap panels, including interactive nested rows and tabs.
• Template variables, Grafana built-in PromQL variables, legend formatting, thresholds, and grid layout support.
• Grafana timeseries draw styles for lines, points, bars, area fill, hidden axes, and per-panel grid visibility.
• Keyboard-first navigation, row/tab/panel search, interactive rows and tabs, fullscreen mode, mouse selection, and value inspection.
• SVG/PNG export and changed-frame recording bundles.
• TOML configuration and built-in themes.
• Read-only external file or command-backed JSONL point annotations with panel targeting, tag filtering, and navigable cluster details.
• Best-effort terminal restoration and recording finalization on normal quit, errors, Ctrl-C, and Unix SIGTERM/SIGHUP.

Documentation

• User guide
• Installation
• Quick start
• Configuration
• External annotations
• Grafana dashboard import
• Grafana compatibility matrix
• Examples

Rust API documentation is available on docs.rs.

Common Commands

# Import a Grafana dashboard
grafatui --prometheus-url http://localhost:9090 --grafana-json ./dashboard.json

# Override Grafana template variables
grafatui --grafana-json ./dash.json --var job=node --var instance=server-01

# Use a theme
grafatui --theme tokyo-night

# Overlay read-only JSONL point events
grafatui --grafana-json ./dashboard.json --annotations-file ./events.jsonl

# Query read-only annotations through a command provider
grafatui --grafana-json ./dashboard.json --annotations-command ./target/debug/examples/git_annotation_provider --annotations-command-arg=.

# Generate shell completions or a man page
grafatui completions zsh
grafatui man

Grafana 13 users can import an exact dashboard.grafana.app/v2 JSON or YAML resource with recursive GridLayout, RowsLayout, TabsLayout, and AutoGridLayout containers. AutoGrid supports responsive columns, fillScreen row growth, and table content fitting with minimum/maximum heights, row matching, and panel-body scrolling; see the compatibility matrix for sizing options and deferred features. AutoGrid item repeats and scoped variables are supported. AutoGrid item conditions support scoped variables, query data and time ranges. Library panels and row/tab conditional rendering remain unsupported; export Model: Classic under Export as code → Advanced options for those dashboards. See the dashboard import guide for the current format requirements.

Contributing

Contributions are welcome. See CONTRIBUTING.md for contribution guidelines and DEVELOPMENT.md for local development notes.

License

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

Copyright 2025 Federico D'Ambrosio