Labsco
samber logo

promql-cli

★ 157

by samber · part of samber/cc-skills

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#git#monitoring
🧩 One of 7 skills in the samber/cc-skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

by samber

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data. npx skills add https://github.com/samber/cc-skills --skill promql-cli Download ZIPGitHub157

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.

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 # list labels for a metric
promql meta # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up' # target a specific host

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

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

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