promtool query: Usage, Options & Common CI Errors
promtool query evaluates PromQL against a live Prometheus from the shell.
promtool query lets a pipeline assert on real metrics - for example, verify an SLO query returns the expected value after a deploy. It hits the Prometheus HTTP API and prints the result.
What it does
promtool query instant runs a PromQL expression at a single point in time against a Prometheus server URL; query range evaluates it over a window. The output can be formatted as text or JSON for downstream assertions.
Common usage
promtool query instant http://localhost:9090 'up'
promtool query instant http://prom:9090 'sum(rate(http_requests_total[5m]))'
promtool query range http://prom:9090 'up' --start=... --end=... --step=1m
promtool query instant -o json http://prom:9090 'up == 0'
promtool query instant --time=2026-06-25T00:00:00Z http://prom:9090 'up'Options
| Subcommand / flag | What it does |
|---|---|
| instant <server> <expr> | Evaluate at a single instant |
| range <server> <expr> | Evaluate over a time window |
| --time <ts> | Evaluation timestamp (instant) |
| --start / --end / --step | Range window and resolution |
| -o json|promql | Output format |
Common errors in CI
"query error: Post \"http://.../api/v1/query\": dial tcp ... connection refused" means Prometheus is not reachable at that URL (wrong host/port, or it is not up). "parse error: ... " indicates invalid PromQL. An empty result set prints nothing and still exits 0 - so "no data" does not fail; pipe to jq -e or grep to assert a value exists. The server argument is a positional URL and must come before the expression; swapping them yields a confusing parse error.