Introduction

Grafatui is a terminal user interface for Prometheus dashboards. It is designed for fast inspection, SSH sessions, local debugging, and environments where opening a browser-based Grafana instance is inconvenient.

Grafatui reads Prometheus directly and can import Grafana dashboard JSON files. It renders supported panels as terminal charts, tables, gauges, stats, and heatmaps while keeping the workflow keyboard-first.

When Grafatui Fits

Use Grafatui when you want:

• A lightweight Prometheus dashboard in your terminal.
• A familiar way to inspect exported Grafana dashboards.
• Fast startup and low resource usage.
• A dashboard that works well over SSH.
• SVG or PNG snapshots of the current TUI view.

Grafatui is not a Grafana server replacement. It does not manage users, alerts, annotations, dashboard editing, plugins, or browser-only visualizations.

Project Links

• Repository
• Crate
• Rust API docs
• Grafana compatibility matrix

Installation

From Crates.io

Install the latest published release with Cargo:

cargo install grafatui

Grafatui currently requires Rust 1.88 or newer.

From Source

Clone the repository and install the local checkout:

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

For development, use cargo run instead:

cargo run -- --prometheus-url http://localhost:9090

Prebuilt Binaries

Prebuilt release assets are published on GitHub Releases for common Linux, macOS, and Windows targets.

Shell Completions

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

# Bash
source <(grafatui completions bash)

# Zsh
source <(grafatui completions zsh)

# Fish
grafatui completions fish | source

Man Page

Generate a man page from the CLI definition:

grafatui man > grafatui.1

Quick Start

Connect to Prometheus

If Prometheus is already running locally:

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

Point Grafatui at another Prometheus server with the same option:

grafatui --prometheus-url http://prometheus.example.com:9090

Import a Grafana Dashboard

Export a Grafana dashboard as JSON, then pass it to Grafatui:

grafatui --prometheus-url http://localhost:9090 --grafana-json ./dashboard.json

Override dashboard variables with repeated --var options:

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

Run the Demo

The repository includes a Prometheus demo stack and sample dashboards:

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

When finished:

cd examples/demo
docker-compose down -v

Useful First Keys

Configuration

Grafatui can be configured with CLI options, a TOML configuration file, or both. CLI options override values from the configuration file.

Common CLI Options

Run the full help output with:

grafatui --help

Configuration File

Create grafatui.toml in ~/.config/grafatui/, or pass a custom path with --config.

prometheus_url = "http://localhost:9090"
refresh_rate = 1000
time_range = "1h"
step = "5s"
theme = "dracula"
threshold_marker = "dashed"
export_dir = "./grafatui-exports"
export_format = "svg"
record_max_frames = 300
autogrid = true
autogrid_color = "dark-gray"
grafana_json = "~/.config/grafatui/my-dashboard.json"

[vars]
job = "node"
instance = "server-01"

Themes

Built-in themes include:

• default
• dracula
• monokai
• solarized-dark
• solarized-light
• gruvbox
• tokyo-night
• catppuccin

Use a theme from the CLI:

grafatui --theme tokyo-night

Grafana Dashboard Import

Grafatui can import Grafana dashboard JSON files and render supported panels in the terminal.

Export From Grafana

1. Open the dashboard in Grafana.
2. Open dashboard settings.
3. Choose the JSON model view.
4. Copy the JSON into a local file.
5. Run Grafatui with --grafana-json.

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

Supported Panel Types

Grafatui currently supports:

• graph
• timeseries
• stat
• gauge
• bargauge
• table
• heatmap

Row panels are traversed so nested panels can be imported, but row headers and collapsed row behavior are not rendered.

Variables

Grafatui reads dashboard variables from templating.list and expands $var and ${var} in PromQL expressions.

Defaults come from the dashboard JSON. Override them from the CLI:

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

Prometheus query variables such as label_values(up, instance) and query_result(...) are resolved before panel queries run.

Import Diagnostics

Grafatui prints import warnings before starting the TUI when a dashboard uses important Grafana features that are skipped or ignored. Diagnostics include unsupported panel types, value mappings, reduce options, unresolved variables, and unsupported variable modifiers such as ${var:regex}.

Run a non-interactive check with:

grafatui --validate --grafana-json ./dash.json

Warnings do not make validation fail. A dashboard that can be parsed and imported exits successfully even if diagnostics are printed.

Use --strict to make warnings fail validation, or --format json to emit a machine-readable summary:

grafatui --validate --strict --grafana-json ./dash.json
grafatui --validate --format json --grafana-json ./dash.json

Hidden Targets

Grafatui honors targets[].hide by skipping hidden targets during import. Panels with a mix of hidden and visible targets render only the visible target queries.

Query Modes

Grafatui honors targets[].instant from Grafana dashboard JSON. Targets marked as instant use the Prometheus instant query endpoint, while range targets use query_range.

If a target does not specify instant, Gauge, Bar Gauge, and Table panels default to instant queries. Graph, Timeseries, Stat, and Heatmap panels default to range queries.

Field Configuration

Grafatui applies selected fieldConfig.defaults values where they map cleanly to terminal rendering:

• min and max set explicit Graph y-axis bounds and Gauge limits.
• thresholds render graph threshold lines and drive dynamic coloring for Stat, Gauge, and Bar Gauge panels.
• unit, decimals, and noValue affect supported panel values, axes, legends, and exports.
• custom.axisGridShow controls per-panel graph guide lines.

Built-In PromQL Variables

Grafatui expands the following Grafana-style variables:

• $__interval
• $__interval_ms
• $__range
• $__range_s
• $__range_ms
• $__rate_interval
• $__rate_interval_ms

Compatibility Details

See the Grafana compatibility matrix for field-by-field support details.

Exporting and Recording

Grafatui can export the current dashboard view as SVG, PNG, or both. It can also record changed dashboard states into a timestamped frame bundle.

Export a Snapshot

Press e to export the current visible dashboard.

Output files are written under --export-dir:

grafatui --export-dir ./grafatui-exports --export-format both

Supported formats:

• svg
• png
• both

Record Changed Frames

Press Ctrl+E to start recording. Press Ctrl+E again, or quit with q, to finalize the bundle.

Grafatui records only changed rendered states:

grafatui-recording-<timestamp>/
  frame-000001.svg
  frame-000002.svg
  manifest.json

If --export-format png or both is selected, matching PNG files are written too.

Recording Limits

Limit the number of changed frames in one recording:

grafatui --record-max-frames 300

When the frame cap is reached, Grafatui stops writing new frames and records completed_reason = "capped" when finalized.

Manifest

Each recording writes a manifest.json file with metadata for downstream tooling:

{
  "version": 1,
  "format": "svg",
  "changed_only": true,
  "frame_count": 2,
  "max_frames": 300,
  "completed_reason": "stopped",
  "viewport": { "width": 100, "height": 40 },
  "frames": [
    {
      "index": 1,
      "elapsed_ms": 0,
      "files": ["frame-000001.svg"]
    }
  ]
}

Keyboard and Mouse

Grafatui is designed for keyboard-first dashboard inspection.

Keyboard Controls

Mouse Support

In normal mode, clicking selects panels. Press v or f to use cursor-focused interactions.

Examples

The repository includes example Grafana dashboards and a local demo environment.

Demo Stack

Start Prometheus, node-exporter, and mock vLLM metrics:

cd examples/demo
docker-compose up -d

Run Grafatui from the repository root:

cargo run -- --grafana-json examples/dashboards/prometheus_demo.json --prometheus-url http://localhost:19090

Stop the demo:

cd examples/demo
docker-compose down -v

Included Dashboards

• examples/dashboards/prometheus_demo.json: recommended first demo for the bundled Prometheus stack.
• examples/dashboards/all_visualizations.json: compact dashboard showing the supported visualization types, including timeseries bars, area fill, point mode, and hidden-axis examples.
• examples/dashboards/instant_queries.json: demonstrates explicit instant targets and the default instant behavior for summary panels.
• examples/dashboards/thresholds_demo.json: demonstrates thresholds, field bounds, and threshold marker rendering.
• examples/demo/vllm/grafana.json: vLLM-oriented dashboard for the mock demo services.

More Detail

See the repository example docs:

• examples/README.md
• examples/demo/README.md

Grafana Dashboard JSON Compatibility

This document provides a comprehensive feature-parity table between the Grafana Dashboard JSON Model and what Grafatui currently supports.

Snapshot: Grafatui v0.1.9. The roadmap prioritizes Grafana parity first, then user-visible product value. See the roadmap for milestone slices built from this compatibility ladder.

Legend:

• ✅ Supported — Fully implemented and working
• 🔶 Partial — Partially implemented or with limitations
• ❌ Not Implemented — Recognized but not yet functional
• ⛔ Not Applicable — Cannot be implemented in a TUI context (e.g., browser-only features)

Dashboard-Level Properties

Panels

Panel Types

Graph & Timeseries Parity

Panel Common Fields

Targets (Queries)

PromQL Special Variables

Templating (Variables)

Variable Substitution

Field Configuration (fieldConfig)

fieldConfig is partially implemented. Thresholds, explicit min/max bounds, selected display formatting fields, threshold style, and per-panel autogrid settings are parsed; value mappings, display names, and field overrides remain major gaps.

Thresholds

Panel Options (options)

Panel-specific options are not parsed yet. Grafatui currently applies its own compact TUI defaults for legends, stat sparklines, gauges, and inspect-mode tooltips.

Annotations

Data Links & Transformations

Alert Rules

Datasource Configuration

Summary Statistics

Most Requested Missing Features

Based on user feedback, the following missing features are most commonly expected:

1. Value mappings (fieldConfig.defaults.mappings) — Map numeric values to text labels
2. Broader unit formatting (fieldConfig.defaults.unit) — Extend the current common-unit subset to more Grafana unit families
3. Reduce options (options.reduceOptions) — Use min/max/mean/total instead of always using the latest value
4. Import diagnostics — Warn clearly about skipped panel types and ignored high-impact fields
5. Additional panel types — text, piechart, histogram, logs

What Grafatui Does Instead

Grafatui provides several TUI-native capabilities that don’t map directly to Grafana JSON features:

This document was reviewed against the Grafatui source code at v0.1.9. If you notice any inaccuracies, please open an issue or PR.

Troubleshooting

Prometheus Connection Refused

Check that Prometheus is running and reachable:

curl http://localhost:9090/-/healthy

If you are using the demo stack, the Prometheus port is 19090:

curl http://localhost:19090/-/healthy

No Data Appears

Prometheus may need a few scrape intervals before data is available. Wait 10 to 15 seconds and force a refresh with r.

Also confirm that the dashboard queries match labels in your Prometheus server:

grafatui --prometheus-url http://localhost:9090 --grafana-json ./dashboard.json --var job=prometheus

Dashboard Variables Do Not Match

Override variables explicitly with --var:

grafatui --grafana-json ./dashboard.json --var instance=localhost:9090

If a Grafana dashboard uses multi-select formatting modifiers such as ${var:csv} or ${var:regex}, check the compatibility matrix. Not every Grafana interpolation mode is implemented.

Demo Port Conflict

The demo Prometheus service uses host port 19090. If that port is already in use, edit examples/demo/docker-compose.yml and run Grafatui with the updated URL.

Export Directory Problems

Set an explicit export directory:

grafatui --export-dir ./grafatui-exports

Make sure the directory is writable by your current user.