plexctl alert

Synopsis

plexctl alert is the operator surface for a Domain's stored alert rules. Alert rules are stored, managed configuration on a Domain: the platform records and serves them but does not evaluate them in this phase, so a stored rule never fires on its own. The family exposes the standard CRUD surface — list, get, create, update, delete — against the per-Domain alert-rules endpoints.

plexctl alert list   --domain <uuid> [flags]
plexctl alert get    --domain <uuid> --id <uuid>
plexctl alert create --domain <uuid> --name <name> --signal <expr> --comparator <gt|gte|lt|lte> --threshold <n> --severity <info|warning|critical> [flags]
plexctl alert update --domain <uuid> --id <uuid> [flags]
plexctl alert delete --domain <uuid> --id <uuid> --yes

Subcommands

plexctl alert list

Drives the ListAlertRules operation (GET /v1/domains/{domainId}/alert-rules) and pages a Domain's stored alert rules, forwarding --cursor and --limit on the query string. In text mode each rule projects onto the columns NAME, SIGNAL, COMPARATOR, THRESHOLD, SEVERITY, ENABLED, ID. In json / yaml mode the typed list shape is emitted verbatim, preserving next_cursor for the caller to page on.

plexctl alert get

Drives the GetAlertRule operation (GET /v1/domains/{domainId}/alert-rules/{alertRuleId}) and fetches a single stored alert rule by id within a Domain. text mode renders the same column projection as list; json / yaml emit the typed AlertRule shape verbatim.

plexctl alert create

Drives the CreateAlertRule operation (POST /v1/domains/{domainId}/alert-rules) and stores a new alert rule on a Domain. --comparator and --severity are validated against their enums at flag-parse time, so a bad value never reaches the wire and exits 2. The created rule is stored, managed configuration only — it is recorded and served, never evaluated. The render projection matches get.

plexctl alert update

Drives the UpdateAlertRule operation (PATCH /v1/domains/{domainId}/alert-rules/{alertRuleId}). Only the flags the operator actually changed are sent on the PATCH body; an absent flag leaves the stored value untouched. The rule remains stored, managed configuration only. The render projection matches get.

plexctl alert delete

Drives the DeleteAlertRule operation (DELETE /v1/domains/{domainId}/alert-rules/{alertRuleId}). The persistent --yes flag must be set; without it the command refuses the destructive delete rather than acting on a single typo of the rule id. On success the server returns 204 No Content and the command prints nothing.

Flags

plexctl alert list

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--cursor	string	no	Continuation token returned by a previous call's next_cursor.
--limit	int	no	Maximum items per page (server default when unset).

plexctl alert get

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--id	string (UUID)	yes	Alert rule UUID.

plexctl alert create

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--name	string	yes	Domain-unique logical name.
--signal	string	yes	Metric or log series expression recorded as the watched signal.
--comparator	string	yes	Crossing direction recorded against the threshold: gt, gte, lt, lte.
--threshold	float	yes	Finite value the signal is recorded against.
--severity	string	yes	Recorded severity classification: info, warning, critical.
--enabled	bool	no	Record the rule as enabled (stored configuration only; defaults to enabled server-side when unset).

plexctl alert update

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--id	string (UUID)	yes	Alert rule UUID.
--name	string	no	New Domain-unique logical name.
--signal	string	no	New watched signal expression.
--comparator	string	no	New crossing direction recorded against the threshold: gt, gte, lt, lte.
--threshold	float	no	New finite threshold value.
--severity	string	no	New recorded severity classification: info, warning, critical.
--enabled	bool	no	New enabled flag (stored configuration only).

plexctl alert delete

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--id	string (UUID)	yes	Alert rule UUID.
--yes	bool	yes	Confirm the destructive delete; inherited from root.

Persistent flags inherited from root

--server, --profile, --token-file, --output, --yes. 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 rule, the page, or the (empty) delete result was rendered to stdout.
1	Transport or API failure, a server-side 5xx, or a malformed response body.
2	Malformed --domain / --id UUID, an invalid --comparator / --severity, 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

Store a new alert rule

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

plexctl alert create \
  --server     "${PLEXSPHERE_URL}" \
  --domain     0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --name       high-cpu \
  --signal     'avg(rate(node_cpu_seconds_total[5m]))' \
  --comparator gt \
  --threshold  0.9 \
  --severity   warning

List a Domain's stored alert rules

plexctl alert list \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1

Update a stored rule's threshold and delete it

plexctl alert update \
  --server    "${PLEXSPHERE_URL}" \
  --domain    0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --id        0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --threshold 0.95

plexctl alert delete \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --id     0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --yes

Cross-references

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