promql-cli — Prometheus Query CLI Skill

promql-cli (github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.

Reference Files

Read the relevant reference file(s) before executing tasks:

For most tasks, read references/usage.md. For PromQL help, read references/promql-reference.md. When debugging, read both references/debugging.md and references/promql-reference.md.

Setup Check

Before running any query, verify that a host is configured:

promql 'up'   # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'

Recognize these errors as a configuration/auth problem and refer to references/installation.md:

If any of these appear, do not create config files on behalf of the user — config files may contain credentials (tokens, passwords) that must never pass through an LLM. Instead, guide the user to set it up themselves:

"Please create ~/.promql-cli.yaml manually with your Prometheus host (and credentials if needed). See references/installation.md for the exact format. Let me know once it's ready."

Only after the user confirms the config is in place should you proceed with queries.

Quick Command Reference

promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output csv                             # CSV output
promql 'up' --output json                            # JSON output
promql metrics                                       # list all metric names
promql labels <metric>                               # list labels for a metric
promql meta <metric>                                 # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host

Key Principles

1. Use `rate()` on counters, never raw values — raw counters only ever increase; the absolute value is meaningless. rate() gives the per-second change rate, which is what you actually care about.
2. When debugging, isolate a single instance — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden behind healthy peers won't show up in averages.
3. Filter early with label matchers in the innermost selector — Prometheus evaluates selectors before functions, so filtering late means scanning all time series. Early filters reduce data scanned and query latency.
4. For histograms, keep `le` in the `by` clause before histogram_quantile() — the function needs all le buckets to interpolate percentiles; dropping le early produces NaN or wrong results.
5. Prefer `--output graph` for range queries — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling.
6. Store credentials in `~/.promql-cli.yaml` and `~/.promql_token`, chmod 600 — passing tokens as CLI args exposes them in shell history and process listings.

This skill is not exhaustive. Please refer to the official promql-cli documentation and examples for up-to-date information. Context7 can help as a discoverability platform.

If you encounter a bug or unexpected behavior in promql-cli itself, open an issue at https://github.com/nalbury/promql-cli/issues.