plexctl metrics

Synopsis

plexctl metrics is the operator surface for a Domain's read-only observability proxy. The family exposes two read subcommands: query evaluates a PromQL instant or range query against the Domain's metrics backend, and capacity reads the per-Domain capacity snapshot. Both subcommands are read-only; the family ships no write or mutate command.

plexctl metrics query    --domain <uuid> --query <promql> [flags]
plexctl metrics capacity --domain <uuid> [flags]

Subcommands

plexctl metrics query

Drives the QueryDomainMetrics operation (GET /v1/domains/{domainId}/metrics/query). The PromQL expression and the window parameters travel on the query string; the control plane proxies the request to the Domain's metrics backend and returns the backend's response envelope unchanged. The subcommand accepts either an instant query (--time) or a range query (--start / --end / --step), plus an optional --node-id Node filter.

The CLI deliberately does not re-parse or re-shape the backend's series envelope. In text mode the result projects onto two columns — STATUS_CODE and BODY — surfacing the verbatim upstream body in a single cell. In json / yaml mode the typed status_code + body shape is emitted verbatim, so an operator who needs the structured series pipes --output json. A malformed --domain is parsed as a UUID locally and exits 2; an --time, --start, or --end value that is not an RFC 3339 timestamp also exits 2.

plexctl metrics capacity

Drives the GetDomainCapacity operation (GET /v1/domains/{domainId}/capacity) and renders the per-Domain capacity snapshot. In text mode each catalogued dimension reading projects onto five columns — DIMENSION, USED, TARGET, RATIO, and UNIT. In json / yaml mode the typed DomainCapacitySnapshot is emitted verbatim, including sampled_at. A malformed --domain exits 2.

Flags

plexctl metrics query

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--query	string	yes	PromQL expression to evaluate.
--time	string (RFC 3339)	no	Evaluation instant for an instant query; when set, range flags are ignored server-side.
--start	string (RFC 3339)	no	Inclusive lower bound of a range query window.
--end	string (RFC 3339)	no	Inclusive upper bound of a range query window.
--step	string	no	Range query resolution step duration (for example 30s, 5m).
--node-id	string (UUID)	no	Optional Node UUID to scope the query to a single Node.

plexctl metrics capacity

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID whose capacity snapshot to read.

Persistent flags inherited from root

--server, --profile, --token-file, --output. See ../plexctl.md for the canonical list.

Exit codes

See ../plexctl.md#exit-code-taxonomy for the inherited base table. The cases that apply to this family:

Code	Trigger
0	The query result or capacity snapshot was rendered to stdout.
1	Transport or API failure, a server-side 5xx, or an upstream-gateway 502 / 504 from the metrics backend collapsing to the generic failure code.
2	Malformed --domain / --node-id UUID, a --time / --start / --end that is not an RFC 3339 timestamp, a missing required flag, or an unknown --output value.
3	Missing or insecure credentials, or a 401 Unauthorized.
4	403 Forbidden, or a 404 Not Found.
77	ReBAC denial (403 Forbidden with reason == "rebac_denied").

Examples

Run an instant PromQL query

export PLEXSPHERE_URL="${PLEXSPHERE_URL:-https://localhost:8080}"

plexctl metrics query \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --query 'up' \
  --time  2026-06-14T12:00:00Z

Run a range query scoped to one Node and emit the structured envelope

plexctl metrics query \
  --server  "${PLEXSPHERE_URL}" \
  --domain  0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --query   'rate(node_cpu_seconds_total[5m])' \
  --start   2026-06-14T11:00:00Z \
  --end     2026-06-14T12:00:00Z \
  --step    30s \
  --node-id 0190a8b8-c2d2-7c2c-9c2c-c2c2c2c2c2c2 \
  --output  json

Read the per-Domain capacity snapshot as YAML

plexctl metrics capacity \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --output yaml

Cross-references

• ../../../../api/openapi/plexsphere-v1.yaml
• ../../../../cmd/plexctl/commands/metrics.go
• ../../../contexts/observability/query.md