prometheus-cli

Capabilities

Ask the question, get an answer you can trust

Run PromQL, find out what is actually being recorded, and read the operational state behind the numbers.

PromQL, both shapes

query instant for the value now, query range for the series behind a graph — plus exemplars, format and parse.

Discover before you query

metadata list gives a metric's type and help text, labels values its label values, and series list exactly what a selector matches.

The step is never implicit

Omit --step and the CLI derives a round resolution for the window — and clamps one that would blow past Prometheus' 11,000-point ceiling. The result says which.

No positional tuples

Prometheus' [timestamp, "value"] pairs come back as named fields with an RFC3339 instant beside the raw epoch — and NaN and +Inf survive intact.

Why the metric is missing

target list --unhealthy for a failing scrape, --state dropped for one relabelling removed, and rule list --failing for a silently broken recording rule.

Flat rules and alerts

Rules are lifted out of their groups into one filterable row each, carrying group, file and their active alerts.

Agent-first output

JSON by default, with structured errors — categories, exit codes and recovery next_steps a coding agent can branch on.

Auth only when there is any

A plain Prometheus needs no credential at all. Behind a gateway, a bearer token or basic auth lives in the OS keychain — plus --tenant for Cortex, Mimir and Thanos.

Multiple servers

kubectl-style named contexts in one config file. Switch the current server, or override per command with --use-context.

Install

Up and running in a minute

Install with npm, then finish setup in two steps — deploy the Skill, then turn on shell completion.

install

# recommended — fetches the prebuilt binary for your platform
npm install -g @angelmsger/prometheus-cli

Other methods — go install, a source build, or a prebuilt binary from the Releases page — are in the README.

Then finish setup:

1 · Companion Skill

A prometheus Skill is embedded in the binary. It detects your coding agents — Claude Code, Codex, Cursor and ten more — and installs for each one found:

$ prometheus-cli skill install
# Re-run after CLI upgrades, then reload the agent context.

2 · Shell completion

Completes subcommands and flag values. Load it once:

$ source <(prometheus-cli completion bash)

Quick start

Point it at a server, then ask

A plain Prometheus needs only a URL. Find the metric, then ask the question.

a typical session

# setup (or just: export PROMETHEUS_URL=http://localhost:9090)
$ prometheus-cli config init --pretty
$ prometheus-cli doctor

# what is down right now
$ prometheus-cli query instant --query 'up == 0'

# find the metric before querying it — the type decides the query
$ prometheus-cli metadata list --metric http_requests_total
$ prometheus-cli labels values job --match 'http_requests_total' --since 1h

# error rate over the last hour; the step is derived and reported
$ prometheus-cli query range --since 1h \
    --query 'sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))'

# an empty result? look at the scrape, not the query
$ prometheus-cli target list --unhealthy
$ prometheus-cli rule list --failing

# what is firing, and is anyone being told
$ prometheus-cli alert list --state firing
$ prometheus-cli alert managers