plexctl logs

Synopsis

plexctl logs is the operator surface for a Domain's read-only logs proxy. The family ships a single read subcommand, query, which evaluates a LogQL expression over an explicit [--from, --to] window and proxies the request to the Domain's logs backend. The family ships no write or mutate command.

plexctl logs query --domain <uuid> --query <logql> --from <ts> --to <ts> [flags]

Subcommands

plexctl logs query

Drives the QueryDomainLogs operation (GET /v1/domains/{domainId}/logs/query). The LogQL expression and the start / end window travel on the query string; the control plane proxies the request to the Domain's logs backend and returns the backend's response envelope unchanged. The window is bounded explicitly by --from and --to rather than a relative duration, so the query bounds stay unambiguous on the wire. Optional --limit, --direction, and --node-id flags refine the scan.

The CLI deliberately does not re-parse or re-shape the backend's stream 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 streams pipes --output json. A malformed --domain or --node-id is parsed as a UUID locally and exits 2; a --from or --to that is not an RFC 3339 timestamp, or a --direction outside backward / forward, also exits 2.

Flags

plexctl logs query

Flag	Type	Required	Description
--domain	string (UUID)	yes	Target Domain UUID.
--query	string	yes	LogQL expression to evaluate.
--from	string (RFC 3339)	yes	Inclusive lower bound of the query window.
--to	string (RFC 3339)	yes	Inclusive upper bound of the query window.
--limit	int	no	Maximum number of log lines to return; clamped server-side.
--direction	string	no	Scan order: backward (newest first) or forward (oldest first).
--node-id	string (UUID)	no	Optional Node UUID to scope the query to a single Node.

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 was rendered to stdout.
1	Transport or API failure, a server-side 5xx, or an upstream-gateway 502 / 504 from the logs backend collapsing to the generic failure code.
2	Malformed --domain / --node-id UUID, a --from / --to that is not an RFC 3339 timestamp, an invalid --direction, 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

Query a Domain's logs over a window

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

plexctl logs query \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --query  '{app="plexd"} |= "error"' \
  --from   2026-06-14T11:00:00Z \
  --to     2026-06-14T12:00:00Z

Tail the most recent lines for one Node as structured output

plexctl logs query \
  --server    "${PLEXSPHERE_URL}" \
  --domain    0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --query     '{app="plexd"}' \
  --from      2026-06-14T11:00:00Z \
  --to        2026-06-14T12:00:00Z \
  --limit     200 \
  --direction backward \
  --node-id   0190a8b8-c2d2-7c2c-9c2c-c2c2c2c2c2c2 \
  --output    json

Cross-references

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