promql-cli

Query Prometheus and PromQL-compatible engines from the command line with instant, range, and discovery subcommands.

Updated May 23, 2026
One-click install
npx skills add https://github.com/Oatse/CWE-Automation --skill promql-cli-oatse
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: promql-cli
Source: https://github.com/Oatse/CWE-Automation/tree/main/.agents/skills/promql-cli
Command: npx skills add https://github.com/Oatse/CWE-Automation --skill promql-cli-oatse

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires promql, jq, and includes references (resource) components.

What problem does it solve? Investigating latency spikes, error rates, and resource saturation requires writing correct PromQL and running it against a Prometheus server, which is error-prone without guidance on metric types, label filtering, and query structure. ## Core Features & Use Cases - Instant and Range Queries: Run PromQL queries against Prometheus, Thanos, Cortex, VictoriaMetrics, or Grafana Mimir with table, CSV, JSON, or ASCII graph output. - Metric Discovery: List metric names, labels, and metadata with the metrics, labels, and meta subcommands before writing queries. - Debugging Methodologies: Apply USE (Utilization, Saturation, Errors) and RED (Rate, Errors, Duration) methods to isolate slow instances and diagnose error spikes. - Use Case: A pod in your Kubernetes cluster is slower than others. Isolate it with a per-instance histogram_quantile query, graph p99 latency over the last two hours, then correlate with CPU and database metrics on that host. ## Quick Start Ask the assistant to graph the HTTP request rate for your API over the last hour using promql-cli.

Frequently Asked Questions about promql-cli

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I query Prometheus from the command line?

Use promql-cli with a PromQL expression, for example promql 'up' for an instant query or promql 'rate(http_requests_total[5m])' --start 1h for a range query. Output formats include table, CSV, JSON, and ASCII graph.

How do I list all metrics in Prometheus with promql-cli?

Run the promql metrics subcommand to list all metric names exposed by your Prometheus instance. Filter with grep, for example promql metrics | grep '^node_', then use promql labels and promql meta to inspect a specific metric.

Should I use rate() or raw counter values in PromQL?

Always wrap counters in rate() or increase() because raw counter values only increase and ignore resets, making absolute values meaningless. Use promql meta <metric> to confirm whether a metric is a counter or a gauge before querying.

Does promql-cli work with Thanos, Cortex, or VictoriaMetrics?

Yes, promql-cli works with any PromQL-compatible engine including Thanos, Cortex, VictoriaMetrics, Grafana Mimir, and Grafana Tempo. Point it at the engine's query endpoint using the --host flag or a config file.

Why does promql-cli return connection refused or 401 errors?

Connection refused means no server is reachable at the configured host, while 401 indicates a missing or invalid bearer token. Verify your ~/.promql-cli.yaml configuration and store credentials in chmod 600 files rather than passing them as CLI flags.

How do I visualize Prometheus metrics in the terminal?

Add --output graph to a range query, for example promql 'node_load1' --start 6h --output graph, to render an ASCII sparkline in the terminal. Graph is the default output for range queries when --start is set.