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:
| File | When to read |
|---|---|
references/installation.md | User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host) |
references/usage.md | User wants to discover metrics/exporters/labels, run queries, or choose output formats |
references/graphing.md | User wants to visualize Prometheus data as an ASCII chart in the terminal |
references/debugging.md | User is investigating a performance issue, latency, errors, or saturation |
references/promql-reference.md | User needs help writing PromQL, understanding metric types, functions, or aggregations |
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:
| Error | Cause |
|---|---|
dial tcp... connection refused | No host running at the configured address |
dial tcp... no such host | Hostname not resolved — wrong host in config |
error querying prometheus:...401... | Bearer token missing or invalid |
error querying prometheus:...403... | Token valid but insufficient permissions |
please specify an authentication type | Auth flags partially set — use config file instead |
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.yamlmanually with your Prometheus host (and credentials if needed). Seereferences/installation.mdfor 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 hostKey Principles
- 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. - 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.
- 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.
- For histograms, keep
lein thebyclause beforehistogram_quantile()— the function needs alllebuckets to interpolate percentiles; droppingleearly producesNaNor wrong results. - Prefer
--output graphfor range queries — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling. - Store credentials in
~/.promql-cli.yamland~/.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.