CLI reference

Global flags

Persistent flags accepted by every command.

prometheus-cli admin

TSDB administration: delete series, clean tombstones, snapshot (writes)

prometheus-cli admin

The TSDB admin endpoints are the only commands in this CLI that change anything. They exist on the server only when it was started with --web.enable-admin-api; without it every one of them returns ADMIN_API_DISABLED (confirm with `status flags`). All three are writes: preview with --dry-run, and they are blocked in read-only mode unless --allow-writes is given. The two that destroy data (delete-series, clean-tombstones) additionally require --yes, and never prompt — so a non-interactive caller fails with a structured error instead of hanging.

prometheus-cli admin clean-tombstones

Erase already-deleted blocks from disk (destructive write)

prometheus-cli admin clean-tombstones [flags]

Removes the blocks that `delete-series` marked, immediately and irreversibly, instead of waiting for the next compaction. It takes no selector: it applies to everything currently marked deleted on this server.

Options

Examples

  prometheus-cli admin clean-tombstones --dry-run
  prometheus-cli admin clean-tombstones --yes

prometheus-cli admin delete-series

Mark the samples matching a selector as deleted (destructive write)

prometheus-cli admin delete-series [flags]

Marks every sample matching the selectors as deleted, optionally within a window. The data stays on disk until the next compaction or a `clean-tombstones`, but it stops being queryable immediately. A selector is required: deleting without one would match everything. Confirm the exact set with `series list --match ...` first — the preview that --dry-run prints is the request, not the affected series.

Options

Examples

  # confirm what the selector matches, preview, then execute
  prometheus-cli series list --match 'up{job="retired"}' --since 30d
  prometheus-cli admin delete-series --match 'up{job="retired"}' --dry-run
  prometheus-cli admin delete-series --match 'up{job="retired"}' --yes

prometheus-cli admin snapshot

Write a TSDB snapshot (write)

prometheus-cli admin snapshot [flags]

Writes a snapshot of the current data under the server's data directory and returns its name. It adds data rather than destroying it, so unlike the other admin commands it needs no --yes — but it does consume disk on the server, and it is still blocked in read-only mode.

Options

Examples

  prometheus-cli admin snapshot --dry-run
  prometheus-cli admin snapshot --skip-head

prometheus-cli alert

Inspect active alerts and the Alertmanagers they go to

prometheus-cli alert

`alert list` is what is firing (or pending) right now, straight from Prometheus rather than from Alertmanager — so it shows alerts before any grouping, inhibition or silencing is applied. `alert managers` shows the Alertmanager endpoints notifications are being delivered to, which is where a firing alert that never arrived is usually explained.

prometheus-cli alert list

List the currently active alerts

prometheus-cli alert list [flags]

Returns each active alert with its state (pending or firing), its labels and annotations, when it became active and how long ago that was. --state and --name filter the result client-side; the endpoint itself takes no parameters.

Options

Examples

  prometheus-cli alert list
  prometheus-cli alert list --state firing
  prometheus-cli alert list --name HighRequestLatency

prometheus-cli alert managers

List the Alertmanager endpoints Prometheus is sending to

prometheus-cli alert managers

Returns the discovered Alertmanagers, active and dropped, in one list with an explicit `state`. An empty active list means notifications are going nowhere, however loudly the rules are firing.

prometheus-cli auth

Log in, check reachability and log out

prometheus-cli auth

Prometheus has no accounts of its own, so a context often needs no credential at all (the `none` scheme). `auth login` stores the secret for the basic / bearer schemes used by a proxy or hosted endpoint; `auth status` reports what this context will send and whether the server answers.

prometheus-cli auth guide

Show offline credential acquisition guidance for this service

prometheus-cli auth guide

Explains where this context's credential actually comes from. Prometheus has no credential page of its own, so the guidance is scheme-specific: the gateway operator for basic, the hosting product for bearer, and nothing at all for none. No request is ever sent to the credential URL.

prometheus-cli auth login

Store credentials for the active context (interactive)

prometheus-cli auth login

Prompts for the credential this context's auth scheme needs — a username and password (basic) or a bearer token (bearer) — verifies it against the server, and stores the secret in the OS keychain. The `none` scheme has nothing to store. Requires an interactive terminal; in CI / agent sandboxes set PROMETHEUS_TOKEN (or PROMETHEUS_USER + PROMETHEUS_PASSWORD) instead.

prometheus-cli auth logout

Remove the stored credential for the active context

prometheus-cli auth logout

prometheus-cli auth reuse

Reuse an existing login in the selected context without signing in again

prometheus-cli auth reuse [flags]

Match stored contexts by complete service URL, authentication scheme and service scope. Verify a matching stored credential before filling a missing personal identity in the selected context. Never copy secrets, replace an existing identity, activate a context, or read credentials from environment variables. Dry-run performs read-only verification and reports the same proposed association. An unchanged or unavailable result is not proof of authentication; use auth status to check.

Options

prometheus-cli auth status

Show what this context sends and whether the server answers

prometheus-cli auth status

Prometheus exposes no identity endpoint, so there is no "who am I" to report. This shows the resolved server, scheme, username and tenant, then calls the build-info endpoint to prove the server is reachable and accepts what the context sends.

prometheus-cli config

Set up and inspect configuration and contexts

prometheus-cli config

prometheus-cli config delete-context

Delete a context and its stored credential

prometheus-cli config delete-context <name>

Delete a context from the config file, together with its stored credential. The credential is kept when another context on the same server URL (host and path) and authentication scheme still uses it; a `none` context has none. When the deleted context was current, the first remaining context becomes current. The only context cannot be deleted.

Examples

  prometheus-cli config delete-context staging

prometheus-cli config get-contexts

List configured contexts and which one is current

prometheus-cli config get-contexts

Examples

  prometheus-cli config get-contexts
  prometheus-cli config get-contexts --format table

prometheus-cli config init

Interactively configure a context and store credentials

prometheus-cli config init [flags]

Collects a server URL, an auth scheme and — for the schemes that need one — a credential, verifies them, then writes a named context plus any secret. A plain Prometheus needs only the URL: the default `none` scheme stores nothing. With --pretty it runs an interactive TUI (requires a terminal); without it, a plain line-by-line wizard that also works over a pipe. When a configuration already exists, it first asks whether to edit a context, add a new one, or replace it all (skip the question with --context <name>). For fully headless setup, set PROMETHEUS_URL and, if needed, PROMETHEUS_TOKEN (or PROMETHEUS_USER + PROMETHEUS_PASSWORD).

Options

Examples

  prometheus-cli config init --pretty   # interactive TUI (recommended)
  prometheus-cli config init             # plain line-by-line wizard (scripts, non-TTY)
  prometheus-cli config init --context prod   # add/update a named context directly

prometheus-cli config set-context

Configure service presets without credentials or network access

prometheus-cli config set-context <name> [flags]

Write service fields from flags, environment or .env over the named target context. Personal environment fields and secrets are ignored. Existing conflicting fields require --overwrite; unrelated contexts and user identities are preserved. The tenant id is a service preset, not an identity, so it is distributed with the URL and scheme.

Options

Examples

  prometheus-cli config set-context team --base-url https://prom.example.com --dry-run
  prometheus-cli config set-context team --base-url https://prom.example.com --activate
  prometheus-cli config set-context mimir --base-url https://mimir.example.com --auth-scheme bearer --tenant team-a

prometheus-cli config show

Show the resolved configuration with field provenance

prometheus-cli config show

prometheus-cli config use-context

Set the current context

prometheus-cli config use-context <name>

prometheus-cli doctor

Check configuration, credentials and connectivity

prometheus-cli doctor [flags]

Runs a quick health check: is a server configured, are credentials present, and can the server be reached and authenticated. Each check reports ok/failed so an agent can self-diagnose environment problems. It also reports whether a newer prometheus-cli release is available.

Options

Examples

  prometheus-cli doctor
  prometheus-cli doctor --no-update-check

prometheus-cli labels

Discover label names and their values

prometheus-cli labels

Labels are how every series is addressed. `labels list` returns the label names present on a server (or within a selector); `labels values <name>` returns the values one label takes. Metric names live in the reserved `__name__` label, so `labels values __name__` is the full metric list.

prometheus-cli labels list

List label names

prometheus-cli labels list [flags]

Returns every label name the server knows, or — with --match — only the names present on the series a selector matches, which is the useful form when composing a `by (...)` or `without (...)` clause.

Options

Examples

  prometheus-cli labels list --since 1h
  prometheus-cli labels list --match 'http_requests_total' --since 1h

prometheus-cli labels values

List the values a label takes

prometheus-cli labels values <label> [flags]

Returns the distinct values of one label. `labels values __name__` is the list of metric names on the server — the starting point when you do not yet know what is being recorded. Narrow with --match to see only the values present on a particular set of series.

Options

Examples

  # every metric name on the server
  prometheus-cli labels values __name__ --since 1h

  # the jobs that report a particular metric
  prometheus-cli labels values job --match 'http_requests_total' --since 1h

prometheus-cli metadata

Look up what a metric is: its type, help text and unit

prometheus-cli metadata

Metric metadata is the difference between guessing at a metric and knowing it. The type decides how it must be queried — a counter needs rate(), a gauge does not — and the help text says what it actually measures. `metadata list` reads the server's aggregated view; `metadata targets` reads it per scrape target, which is how you find a disagreement between two exporters of the same metric name.

prometheus-cli metadata list

List metric metadata (type, help, unit)

prometheus-cli metadata list [flags]

Returns one row per metric name with its type, help text and unit, sorted by name. Narrow to a single metric with --metric before writing a query against it. --limit defaults to a bounded page; pass --limit 0 to lift it.

Options

Examples

  prometheus-cli metadata list --metric http_requests_total
  prometheus-cli metadata list --limit 100

prometheus-cli metadata targets

Show metric metadata as individual scrape targets report it

prometheus-cli metadata targets [flags]

Returns metadata per target rather than aggregated, each row carrying the target's labels. Use it when the same metric name is exported by more than one job and you need to know which definition a series came from.

Options

Examples

  prometheus-cli metadata targets --metric http_requests_total
  prometheus-cli metadata targets --match-target '{job="node"}'

prometheus-cli query

Run PromQL queries (instant, range and exemplars)

prometheus-cli query

Query is the heart of the CLI. `query instant` evaluates an expression at a single point in time and returns one value per series; `query range` evaluates it repeatedly across a window and returns the series behind a graph. `query format` and `query parse` check an expression without evaluating it. Results are normalized: Prometheus' positional [timestamp, "value"] tuples come back as named fields with an RFC3339 instant alongside the raw epoch. Discover what to query with `metadata list` (metric names and their help text), `labels list` / `labels values` (label names and values) and `series list` (the exact series a selector matches).

prometheus-cli query exemplars

List the trace exemplars attached to a selector

prometheus-cli query exemplars [flags]

Returns the exemplars recorded alongside samples over a window — the trace ids that link a metric spike to the requests that caused it. The window is required, and the server must have exemplar storage enabled.

Options

Examples

  prometheus-cli query exemplars --query 'http_request_duration_seconds_bucket' --since 1h

prometheus-cli query format

Pretty-print a PromQL expression (and confirm it parses)

prometheus-cli query format [flags]

Asks the server to re-render an expression in its canonical form. It is the cheapest way to confirm an expression is syntactically valid before running it against a large window.

Options

Examples

  prometheus-cli query format --query 'sum  by(job)(rate(  up[5m] ))'

prometheus-cli query instant

Evaluate a PromQL expression at a single instant

prometheus-cli query instant [flags]

Runs an instant query. The result is one value per matching series at the evaluation time, which defaults to now. This is the shape to use for "what is it right now" and for any aggregate you intend to read as a single number.

Options

Examples

  # current request rate per service
  prometheus-cli query instant --query 'sum by (service) (rate(http_requests_total[5m]))'

  # which targets are down right now
  prometheus-cli query instant --query 'up == 0'

  # evaluate at a past instant
  prometheus-cli query instant --query 'up' --time 2026-01-02T15:04:05Z

prometheus-cli query parse

Show the server's parse tree for a PromQL expression

prometheus-cli query parse [flags]

Returns the abstract syntax tree Prometheus builds for an expression. Use it to see exactly how an expression was interpreted — which operator binds where, what a selector's matchers resolved to — when a query returns something other than what was intended.

Options

Examples

  prometheus-cli query parse --query 'rate(http_requests_total[5m]) > 0.5'

prometheus-cli query range

Evaluate a PromQL expression across a time window

prometheus-cli query range [flags]

Runs a range query: the expression is evaluated at every step between the start and end of the window, yielding a timestamped series per result — the data behind a graph. The window is required: --since, or --from with an optional --to. --since cannot be combined with --from/--to, and --to requires --from. --step is optional. Prometheus rejects a range query resolving to more than 11,000 points per series, so with no --step the CLI derives a round resolution for the window, and an explicit --step that would overrun the limit is raised rather than sent. The step actually used, its source (flag / derived / clamped) and the resulting point count come back in the result, so the resolution behind the numbers is never implicit.

Options

Examples

  # error rate over the last hour, resolution chosen for you
  prometheus-cli query range --query 'sum(rate(http_requests_total{status=~"5.."}[5m]))' --since 1h

  # an explicit window and resolution
  prometheus-cli query range --query 'up' --from 2026-01-02T00:00:00Z --to 2026-01-02T06:00:00Z --step 5m

  # a long expression read from a file, streamed one series per line
  prometheus-cli query range --query @slo.promql --since 24h --format ndjson

prometheus-cli rule

Inspect recording and alerting rules

prometheus-cli rule

Rules are the queries Prometheus evaluates on a schedule: recording rules that precompute a series, and alerting rules that fire alerts. The CLI flattens them out of their groups into one row per rule carrying `group`, `file` and the group's evaluation interval, so a failing rule can be found and reported without walking a nested document.

prometheus-cli rule list

List rules, with their health and active alerts

prometheus-cli rule list [flags]

Returns the configured rules. --type narrows to alerting or recording rules; --name, --group and --file filter by exact identifier (discover all three from an unfiltered listing); --failing keeps only the rules whose last evaluation errored, which is the fastest path to a broken recording rule. Alerting rules carry their currently active alerts. On an instance with many firing alerts that is the bulk of the response — pass --exclude-alerts to drop it. Use --group-limit to page by rule group and resume with the returned --cursor.

Options

Examples

  prometheus-cli rule list --type alert
  prometheus-cli rule list --failing
  prometheus-cli rule list --group node-alerts --exclude-alerts

prometheus-cli series

Discover the series a selector matches

prometheus-cli series

A series is one unique label set. `series list` answers "what exactly does this selector match" without evaluating any samples — the step to take before a query that returns nothing, or one that would return far more series than expected.

prometheus-cli series list

List the label sets matching one or more selectors

prometheus-cli series list [flags]

Returns one entry per matching series: its __name__ lifted out as `name`, and the full label set as `metric`. Pass --match more than once to union several selectors. The window is optional but recommended: without it the server scans its whole retention. --limit defaults to a bounded page so a stray call on a large instance cannot flood an agent's context; pass --limit 0 to lift it.

Options

Examples

  prometheus-cli series list --match 'up{job="node"}' --since 1h
  prometheus-cli series list --match 'http_requests_total' --match 'up' --since 6h --limit 50

prometheus-cli skill

Install the companion Skill for coding agents

prometheus-cli skill

prometheus-cli skill install

Deploy the embedded Skill into a coding agent's skills directory

prometheus-cli skill install [flags]

Write the companion `prometheus` Skill — bundled inside this binary — into a coding agent's skills directory. With no flags it probes for installed agents (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) and installs into each one found. Re-run it after upgrading the CLI to refresh the Skill to the matching version, then reload the agent context.

Options

prometheus-cli skill path

Print Skill paths, installation state and version alignment

prometheus-cli skill path [flags]

Options

prometheus-cli skill show

Print the embedded SKILL.md to stdout

prometheus-cli skill show

prometheus-cli skill status

Report loaded, installed and embedded Skill versions

prometheus-cli skill status [flags]

Options

prometheus-cli skill uninstall

Remove the companion Skill from a coding agent's skills directory

prometheus-cli skill uninstall [flags]

Delete a previously installed `prometheus` Skill. With no flags it probes for installed agents (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) and removes the Skill from each one found.

Options

prometheus-cli status

Read the server's configuration, flags and storage stats

prometheus-cli status

Status answers questions about the server rather than the data: what it was configured with, which flags it was started with (including whether the admin API is enabled), what its storage looks like, and whether it is still replaying its write-ahead log. Each topic is a separate subcommand so every accepted value is discoverable from --help.

prometheus-cli status buildinfo

Show the server's version and build metadata

prometheus-cli status buildinfo

Returns the version, revision and Go build details. The version decides which API endpoints and PromQL features exist, so it is worth reading before concluding that a missing endpoint is a configuration problem.

prometheus-cli status config

Show the server's running configuration (YAML)

prometheus-cli status config

Returns the configuration Prometheus is currently running, as a YAML document under `yaml`. This is the reloaded state, not what is on disk — the two differ whenever a change has not been reloaded.

prometheus-cli status flags

Show the command-line flags the server was started with

prometheus-cli status flags

Returns the server's flag values. This is where to confirm the retention period, the storage path, and whether --web.enable-admin-api is on (the admin commands need it).

prometheus-cli status notifications

Show the server's active notifications

prometheus-cli status notifications

Returns the notifications Prometheus is surfacing about itself — the same banners its web UI shows. Available on newer servers only.

prometheus-cli status runtimeinfo

Show runtime state: uptime, reload time, goroutines, storage retention

prometheus-cli status runtimeinfo

Returns live runtime state including start time, last successful configuration reload, and current time-series counts. A last-reload time older than a config change means the change has not taken effect.

prometheus-cli status tsdb

Show storage cardinality: the biggest metrics, labels and label values

prometheus-cli status tsdb [flags]

Returns the head block's cardinality tables — the series count by metric name, by label pair, and the labels consuming the most memory. This is the direct answer to "what is making this server slow or large".

Options

prometheus-cli status wal-replay

Show write-ahead-log replay progress

prometheus-cli status wal-replay

Returns WAL replay progress. A server still replaying answers queries with incomplete data, so a surprising empty result right after a restart is explained here rather than in the query.

prometheus-cli target

Inspect scrape targets and why they are failing

prometheus-cli target

Targets are what Prometheus scrapes. When a metric is missing the cause is usually here, not in the query: a target that is down, one that was never discovered, or one dropped by relabelling. Active and dropped targets come back in one list with an explicit `state`, each carrying its health, last scrape time (absolute and relative) and last error.

prometheus-cli target list

List scrape targets, active and dropped

prometheus-cli target list [flags]

Returns the scrape targets. --state active|dropped|any narrows which the server sends; --scrape-pool narrows to one pool; --unhealthy keeps only the active targets Prometheus does not consider up, which is the direct answer to "what is broken right now". A dropped target has no post-relabelling labels, so its identity is reported from `discovered_labels` — the only place the reason it was dropped is visible.

Options

Examples

  prometheus-cli target list --unhealthy
  prometheus-cli target list --state dropped
  prometheus-cli target list --scrape-pool node

prometheus-cli version

Print version information

prometheus-cli version