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

Homebrew

Install Grafatui with Homebrew on macOS or Linux:

brew install fedexist/grafatui/grafatui

Installer Script

Install the latest prebuilt release without requiring Rust:

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

With wget:

bash -o pipefail -c 'wget -O- https://raw.githubusercontent.com/fedexist/grafatui/main/install.sh | bash'

The script supports Linux and macOS on x86_64 and ARM64. It installs to $HOME/.local/bin and never invokes sudo. Make sure that directory is on your PATH.

Set GRAFATUI_INSTALL_DIR to choose another destination:

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

Set GRAFATUI_VERSION to install a specific release. The leading v is optional:

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

Every release download is verified against its published SHA-256 checksum manifest. Installation stops if the manifest is unavailable or verification fails.

Reviewing downloaded scripts before running them is recommended:

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

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

Grafatui imports either a Classic JSON dashboard or an exact dashboard.grafana.app/v2 JSON resource that uses a GridLayout:

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

For advanced V2 dashboards that use rows, tabs, auto-grid, repeat, conditional rendering, nested variables, or library panels, use the Classic export fallback: open Export as code → Advanced options, set Model to Classic, then download or copy the JSON. V1 Resource and Resource YAML files are unsupported. See Grafana Dashboard Import for the full format requirements.

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"
annotations_file = "./events.jsonl"

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

External Annotation Sources

Select one read-only annotation source: annotations_file or the nested [annotations_command] table. The two TOML forms conflict. The --annotations-file CLI flag conflicts with every command-source CLI flag; CLI source selection still replaces the complete TOML annotation source.

[annotations_command]
program = "./target/debug/examples/git_annotation_provider"
args = ["."]
timeout = "10s"

program is required; args defaults to an empty list and timeout defaults to 10s. The matching CLI source is:

grafatui \
  --annotations-command ./target/debug/examples/git_annotation_provider \
  --annotations-command-arg=. \
  --annotations-command-timeout 10s

--annotations-command-arg and --annotations-command-timeout require --annotations-command; repeat the argument flag to retain argument order. --annotations-file and --annotations-command cannot be combined. A CLI file or command has whole-source precedence over TOML: it replaces the configured file or complete command configuration rather than merging individual fields.

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

External Annotations

Grafatui can overlay read-only, external point events from exactly one source: a JSONL file or a command provider. It never edits or writes either source. External annotations are deliberately separate from Grafana dashboard annotations: Grafatui does not implement Grafana annotation queries, APIs, annotations, or annotations.list.

Enable Annotations

Select exactly one source. For a file source, pass the path on the command line:

grafatui \
  --grafana-json ./dashboard.json \
  --annotations-file ./events.jsonl

Or configure the file source in TOML:

annotations_file = "./events.jsonl"

For a command source, configure an executable that accepts the request protocol below. The command receives no shell interpolation:

[annotations_command]
program = "./target/debug/examples/git_annotation_provider"
args = ["."]
timeout = "10s"

Or select it from the command line:

grafatui \
  --grafana-json ./dashboard.json \
  --annotations-command ./target/debug/examples/git_annotation_provider \
  --annotations-command-arg=.

File and command sources are mutually exclusive. A TOML configuration that sets both is rejected even if the CLI selects a source. A CLI file or command replaces the complete TOML annotation source; it never mixes a CLI program, arguments, or timeout with TOML values. Sources are opt-in and read-only; Grafatui does not create, edit, or otherwise write them.

Command Provider Protocol

Grafatui writes exactly one version-1 request line to the command’s standard input, then closes stdin. The request defines the complete refresh window:

{"version":1,"range":{"from":"2026-08-12T10:00:00Z","to":"2026-08-12T10:05:00Z"}}

range.from and range.to are inclusive UTC RFC 3339 bounds. Grafatui defensively applies its visible-range filtering to the events returned.

The provider writes zero or more existing JSONL events to stdout and diagnostics to stderr. Exit 0 with valid bounded JSONL replaces the complete annotation snapshot; an empty successful stdout clears it. A spawn failure, timeout, nonzero exit, invalid UTF-8 or JSONL, or oversized stdout keeps the last valid snapshot and shows a warning.

The default timeout is 10 seconds. Grafatui accepts at most 10 MiB of stdout and captures at most 64 KiB of stderr. Providers inherit Grafatui’s current directory and environment. Put credentials in that environment or use standard credential tooling; never place secrets in dashboard JSON or command arguments.

The included Git provider is a practical starting point:

cargo build --example git_annotation_provider
printf '%s\n' '{"version":1,"range":{"from":"2026-08-12T10:00:00Z","to":"2026-08-12T10:05:00Z"}}' \
  | ./target/debug/examples/git_annotation_provider .

JSONL Event Format and Targeting

The file contains one JSON object per line. Blank lines are ignored. Each event requires time to be an RFC3339 string with an explicit timezone or offset (numeric timestamps are rejected) and non-empty text. tags is an optional array of non-empty strings.

{"time":"2026-07-23T14:30:00Z","text":"Maintenance window","tags":["maintenance"]}
{"time":"2026-07-23T14:30:00Z","text":"Deployed v2.4","tags":["deploy","production"],"panel_titles":["HTTP Request Rate by Status Code"]}

Omit panel_titles to target all eligible graph and timeseries panels, as in the first event. When panel_titles is present, it must contain one or more non-blank titles and each title is matched exactly and case-sensitively against eligible graph/timeseries panel titles. null, an empty array, and blank titles are validation errors.

If a title occurs on multiple eligible panels, the event fans out to all of them and Grafatui shows one warning for that duplicate title. A title that is missing, or exists only on a non-graph panel, shows one warning and renders no marker for that title. These titles are Grafatui routing labels, not Grafana panel IDs.

Events are ordered by timestamp. Unknown JSON fields are ignored. Times with fractional seconds are accepted, and the full fractional timestamp is used when projecting an event onto the graph even when the space-limited inline timestamp display shows less precision.

Target, Filter, Inspect, and Reload

This walkthrough uses current UTC timestamps so both events fall in the visible 15-minute range. It uses only POSIX shell tools; no jq is required.

First, start the bundled Prometheus demo stack from the repository root:

cd examples/demo && docker-compose up -d && sleep 5 && cd ../..

Then create the annotation file and run Grafatui:

annotation_demo_file=/tmp/grafatui-annotations-demo.jsonl
annotation_demo_time="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"

printf '{"time":"%s","text":"Maintenance window","tags":["maintenance"]}\n' \
  "$annotation_demo_time" > "$annotation_demo_file"
printf '{"time":"%s","text":"API deployed","tags":["deploy","production"],"panel_titles":["HTTP Request Rate by Status Code"]}\n' \
  "$annotation_demo_time" >> "$annotation_demo_file"

cargo run -- \
  --grafana-json examples/dashboards/prometheus_demo.json \
  --prometheus-url http://localhost:19090 \
  --range 15m \
  --annotations-file "$annotation_demo_file"

Maintenance window appears on every graph/timeseries panel. API deployed appears only on HTTP Request Rate by Status Code. Press t, select deploy with Space, and press Enter; only the targeted deployment remains. Press v, move the cursor to the marker, and press Enter; the selected panel’s cluster list and selected-event detail pane open.

While Grafatui is running, append an event in a second terminal:

annotation_demo_file=/tmp/grafatui-annotations-demo.jsonl
annotation_demo_time="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
printf '{"time":"%s","text":"Rollback started","tags":["rollback","production"],"panel_titles":["HTTP Request Rate by Status Code"]}\n' \
  "$annotation_demo_time" >> "$annotation_demo_file"

The new event is loaded after the normal refresh; Grafatui does not need to restart. With only deploy selected, Rollback started remains hidden. Press t, then c, and press Enter to apply the cleared filter and reveal the rollback marker. Alternatively, select rollback in the filter and apply it.

Tag Filter and Cluster Controls

Press t to open the global annotation tag filter. It is runtime-only: it is not written to the JSONL source or configuration, and applies to every eligible panel. Selected tags use exact, case-sensitive OR matching: an event remains visible when it has any selected tag. With no selected tags, events with and without tags remain visible. The catalogue keeps a selected tag with a zero event count so it can be removed after a reload.

In the tag filter, use Up/Down or j/k to move, Space to toggle the highlighted tag, c to clear the draft, Enter to apply it, or Esc to cancel without changing the applied filter. In inspection mode, Enter opens only the cluster actually rendered by the selected panel at the cursor. In the cluster, use Up/Down or j/k to select an event, PgUp/PgDn to page, and Enter or Esc to close. Mouse input is ignored while either annotation modal is open.

Cluster contents are frozen when the cluster opens: a later reload can replace the live annotation snapshot without moving rows or changing the cluster’s event details.

Automatic Reload, Rendering, and Exports

Grafatui refreshes both source types during each normal refresh, including while markers are hidden. It checks a file source’s metadata and, when it changes, reads, parses, and validates the full candidate file before atomically replacing the snapshot. A zero-byte file is a valid update that clears all events. Command and Prometheus refreshes share the same time range, start together, and redraw together. Annotation loading is independent of Prometheus: annotation failures never fail startup or a Prometheus refresh.

Only graph and timeseries panels receive annotation markers. Press a to toggle marker visibility. Events that project to the same terminal column are shown as one counted marker: • for one event, decimal 2–9 for two through nine events, and + for 10 or more. In inspection mode, moving the cursor onto that column shows the cluster’s timestamp, text, and tags inline; multi-event details report the exact cluster count.

Applied panel targeting and tag filtering affect the markers in SVG/PNG exports and changed-frame recordings. Active inline annotation details are exportable; the tag-filter and cluster modal chrome is not.

Errors and Last Valid Snapshot

If a file is missing, unreadable, or contains a malformed event, Grafatui keeps rendering the last valid snapshot and shows an annotation warning. Command provider failures follow the same rule. A bad update does not replace the previously loaded events, fail startup, or fail the Prometheus refresh.

CI/CD and Provider Integrations

CI workflow → durable deployment/release record → command provider query
            → normalized JSONL point events → Grafatui overlay

GitHub Actions is a useful concrete pattern: let a workflow record deployment, release, or workflow outcomes in an API, object store, database, or shared event log. A local provider receives Grafatui’s requested range and queries that system of record, then emits normalized JSONL point events. Useful tags include repository, workflow, environment, status, commit, and deployment.

Give the provider credentials through its environment or standard credential tooling, never dashboard JSON or command arguments. A shared JSONL file is a reasonable source only when the workflow and Grafatui genuinely share storage; do not commit an ever-growing event log to the application repository. Vendor-specific providers should normally live as user or community plugins. Built-in integrations remain demand-driven.

Current Limits and Roadmap

This feature supports one external file or command source, point events, panel-title routing, and one global runtime-only tag filter. It has no stable event IDs, no per-panel tag filters, no multiple sources, and no editing. It does not add Grafana annotation-query/API compatibility. Range events, stable event IDs, and per-panel tag filters remain deferred. --validate validates Grafana dashboard imports only; it does not validate annotations.

Grafana Dashboard Import

Grafatui imports supported Grafana dashboard JSON files and renders supported panels in the terminal.

The supported V2 subset maps inline Panel elements, Prometheus PanelQuery queries, top-level variables, timeSettings.autoRefresh, supported field configuration, and fixed-grid positions to the same Grafatui behavior as Classic JSON.

V2 layouts other than GridLayout (including Rows, Tabs, and Auto-grid) are fatal import errors. Repeated grid items are also rejected rather than silently changing the dashboard.

Export From Grafana

1. Open the dashboard in Grafana.
2. In the toolbar, open Export and select Export as code.
3. Expand Advanced options.
4. Set Model to Classic.
5. Download the file, or copy the JSON into a local .json file.
6. Run Grafatui with --grafana-json.

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

Grafana 13 defaults to the V2 Resource model. Its fixed-grid JSON resources can be imported directly. For advanced V2 dashboards, use this Classic export path as the fallback. Grafana documents the available models and export controls in Export a dashboard as code.

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, unsupported V2 datasources, and unsupported variable modifiers such as ${var:regex}. V2 diagnostics retain their spec.* source paths.

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. Fatal V2 layout and repeat errors fail validation in all modes; --strict additionally fails when import diagnostics are present:

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.

When external annotations are visible, their panel targeting and applied tag filter affect the markers written to SVG/PNG exports and changed-frame recordings. Any active inline annotation details remain exportable. Annotation modal chrome is omitted from exports and recordings, and draft-only tag-filter edits do not create recording frames; a frame can change after the filter is applied or cleared.

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.

Annotation Modals

The global tag filter opens with t. Use Up/Down or k/j to move, Space to toggle the highlighted tag, c to clear the draft, Enter to apply it, or Esc to discard it. In an annotation cluster, use Up/Down or k/j to select an event, PgUp/PgDn to page, and Enter or Esc to close it. Mouse input is ignored while either annotation modal is open.

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/dashboards/grafana_v2_compatibility.json: exact Grafana V2 resource with a GridLayout, a dynamic Prometheus job variable, refresh settings, and two supported panels. Run it with:

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

• 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 models and what Grafatui currently supports.

Snapshot: Grafatui v0.1.11. 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 Schema Models

Grafatui imports the non-resource Classic JSON model and a fixed-grid subset of the V2 Resource JSON model. In Grafana 13, use Export as code → Advanced options → Model: Classic as the fallback for advanced V2 dashboards. See the dashboard import guide for detailed steps.

V2 Resource JSON Subset

Grafana V2 Resource YAML remains unsupported. Use a Classic export for any advanced V2 dashboard outside this fixed-grid subset.

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

Grafatui external file/command JSONL events are a separate, opt-in read-only source. panel_titles is Grafatui’s external-source routing field: it matches eligible graph/timeseries panel titles exactly, not Grafana panel IDs. It does not imply compatibility with Grafana annotation queries, APIs, annotations, or annotations.list.

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.11. 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.