promql-cli — Prometheus Query CLI Skill

promql-cli

Reference Files

references/installation.md

references/usage.md

references/graphing.md

references/debugging.md

references/promql-reference.md

references/usage.md

references/promql-reference.md

references/debugging.md

references/promql-reference.md

Setup Check

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

references/installation.md

dial tcp ... connection refused

dial tcp ... no such host

error querying prometheus: ...401...

error querying prometheus: ...403...

please specify an authentication type

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

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.