plexctl hook

Synopsis

plexctl hook is the operator surface for inspecting the hooks plexd discovered on Nodes. The family is discovery-only and read-only: plexsphere records what plexd observed in the customer cluster and never writes hooks back, so there is no create / update / delete affordance. Each row is a projection of an upstream Kubernetes PlexdHook custom resource and reports whether the discovered image digest matches the digest declared in the Node's capability manifest.

Both subcommands ultimately read the same projection served by GET /v1/hooks (ListHooks) — the only hooks operation the /v1 API exposes. get adds no server round-trip of its own kind; it is a client-side filter over the same list (see below).

plexctl hook list [flags]
plexctl hook get  <name>

Subcommands

plexctl hook list

GETs /v1/hooks and renders one row per discovered hook visible to the caller. Optional --domain-id / --project-id residency filters and an optional --image-digest-match drift filter compose to narrow the page; pagination is keyset-based via --cursor / --limit, with the response carrying a next_cursor the caller threads back into the next --cursor.

The --image-digest-match filter is tri-state: leaving the flag unset returns matching and mismatching rows alike; setting it forwards the chosen boolean so only matches (true) or only mismatches (false) are returned. Each row reports NAME, NODE_ID, DOMAIN_ID, IMAGE_DIGEST, and IMAGE_DIGEST_MATCH.

plexctl hook get

Fetches a single discovered hook by name. There is no server-side single-hook operation — the read API exposes only the list projection — so get is implemented as a client-side scan: it pages /v1/hooks following next_cursor and returns the first row whose name matches the positional <name> argument. The scan is bounded by a page cap so a mistyped name can never spin the CLI across an unbounded result set. When no page contains a matching name the command fails rather than returning an empty result.

Because get reuses the list endpoint, it shares the list authorisation path and renders the same columns as a single-row table.

Flags

plexctl hook list

Flag	Type	Default	Required	Description
--domain-id	string (UUID)	(empty)	no	Optional owning-Domain UUID filter. Forwarded only when set; a malformed value exits 2.
--project-id	string (UUID)	(empty)	no	Optional Project UUID filter. Forwarded only when set; a malformed value exits 2.
--image-digest-match	bool	false	no	Drift filter. Forwarded only when the flag is explicitly set: true returns only matching digests, false only mismatches. Unset leaves the page unfiltered.
--cursor	string	(empty)	no	Continuation token returned by a previous call's next_cursor. The token is HMAC-signed; a tampered cursor surfaces as 400 on the next call.
--limit	int	0	no	Maximum items per page; the server uses its default when zero and clamps the forwarded value to [1, 200].

plexctl hook get

plexctl hook get takes a single positional argument and no command-specific flags.

Argument	Type	Required	Description
<name>	string	yes	Discovered hook resource name to locate by scanning the list projection.

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 (0 / 1 / 2 / 3 / 4 / 77). The branches that apply to this family:

Condition	Exit code
Successful list or get	0
get <name> finds no matching row in the scanned pages	1
Malformed --domain-id / --project-id UUID, unknown flag, or unknown --output format	2
Missing --server / token, or server 401	3
Server 403 Forbidden	4
Server 403 with rebac_denied	77

Examples

List discovered hooks visible to the caller

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

plexctl hook list --server "${PLEXSPHERE_URL}"

Narrow to drifted hooks in a Project

plexctl hook list \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --image-digest-match=false \
  --output     json

Page through the projection

plexctl hook list \
  --server "${PLEXSPHERE_URL}" \
  --limit  50 \
  --cursor "$(cat ./next-cursor.txt)"

Fetch a single discovered hook by name

plexctl hook get nightly-scan \
  --server "${PLEXSPHERE_URL}" \
  --output json

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml
• ../../../cmd/plexctl/commands/hook.go
• ../../api/hooks.md — the matching /v1/hooks HTTP reference.