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"
scrape_interval = "15s"
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"

Private CAs and Mutual TLS

TLS settings are optional. Without them, plain HTTP and public HTTPS behave as before. To connect to a Prometheus server using a private CA and mutual TLS:

prometheus_url = "https://prometheus.internal:9090"

[tls]
ca_cert = "~/.config/grafatui/tls/ca.pem"
client_cert = "~/.config/grafatui/tls/client.pem"
client_key = "~/.config/grafatui/tls/client.key"

The equivalent CLI options are:

grafatui --prometheus-url https://prometheus.internal:9090 \
  --ca-cert ca.pem \
  --client-cert client.pem \
  --client-key client.key

• ca_cert may contain multiple PEM CA certificates. They augment the built-in public roots rather than replacing them.
• client_cert contains the client certificate followed by any intermediate certificates. client_key accepts an unencrypted RSA, SEC1 EC, or PKCS#8 PEM private key. The two options must be set together.
• CLI values override matching [tls] values one by one. Paths beginning with ~ are expanded after precedence is resolved.
• TLS options require an https:// Prometheus URL. There is no insecure certificate-verification bypass.
• Unknown [tls] keys are rejected. File and parsing errors identify the option and path without including certificate or private-key contents.

Query Resolution

When step/--step is absent, range queries choose their step the way Grafana’s Prometheus datasource does:

1. Divide the time range by the panel’s maxDataPoints, or by 1000 when it is unset.
2. Round to a Grafana interval, such as 20s, 1m, or 10m.
3. Use the min interval instead when it is larger. The min interval is the target’s interval, then the panel’s interval, then 5s.
4. Coarsen the step if the query would exceed Prometheus’s limit of 11,000 points per series.

An explicit --step or configured step is used exactly. It is not rounded, coarsened for the time range, or overridden by imported panel/target intervals.

$__interval is the step a query runs with. $__rate_interval is max($__interval + scrape interval, 4 × scrape interval). The scrape interval is the query’s min interval in automatic mode when the dashboard sets one, and --scrape-interval otherwise. Explicit-step mode always uses --scrape-interval for this calculation.

With the defaults, a 5m or 1h range queries every 5s, 24h every 1m, and 7d every 10m. The title bar shows the step for panels without their own query options.

Prometheus Request Limits and Retries

Grafatui reads at most 64 MiB from one Prometheus response and keeps at most 64 complete range-query windows in its in-memory cache. Identical in-flight range queries share one request; cancelling their leader releases waiting callers so a later refresh can retry normally.

Transport failures, HTTP 429, and HTTP 5xx responses are retried with the existing bounded backoff. Rejected HTTP 4xx queries, malformed responses, and responses over the 64 MiB limit are not retried. Error excerpts are bounded and remain valid UTF-8.

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