plexctl capability

Synopsis

plexctl capability is the operator surface for inspecting the per-Node capability manifest rows scoped to a Project. Each row reports the checksum status of a Node's running agent binary against the known-good artifact set:

• match — the reported checksum equals a known-good artifact.
• drift — the reported checksum differs from every known-good artifact.
• unknown — no known-good artifact is on record for comparison.

The family is read-only. The /v1 surface exposes exactly one capabilities operation — GET /v1/projects/{project_id}/capabilities (ListCapabilities) — and both subcommands consume it. Per-row visibility is layered on the persistence-level page, so each call returns the subset the caller is authorised to see.

plexctl capability list --project-id <uuid> [flags]
plexctl capability get  <node-id> --project-id <uuid>

Subcommands

plexctl capability list

GETs /v1/projects/{project_id}/capabilities and renders one row per visible Node. An optional --node-id narrows the page to a single Node and an optional --status filters by checksum status; both are passed through to the server as query parameters. Pagination is cursor-based via --cursor / --limit; the response carries a next_cursor the caller threads into the next --cursor to walk the pages.

plexctl capability get <node-id>

Fetches the single capability row for one Node. There is no server-side single-capability endpoint — get is a client-side projection over the same ListCapabilities operation: it issues the list call narrowed by the node_id filter and renders the first returned row. An empty page means the Node has no capability row visible to the caller; that is surfaced as an error (exit 1) rather than as empty output.

Flags

plexctl capability list

Flag	Type	Required	Description
--project-id	string (UUID)	yes	Owning Project UUID whose capability rows to list.
--node-id	string (UUID)	no	Optional Node UUID filter; returns only that Node's row.
--status	string	no	Checksum-status filter: match, drift, or unknown. An unknown value is rejected client-side and exits 2.
--cursor	string	no	Continuation token returned by a previous call's next_cursor.
--limit	int	no	Maximum items per page (server default when zero).

plexctl capability get <node-id>

The Node UUID is a positional argument (<node-id>), not a flag; exactly one is required and malformed input exits 2.

Flag	Type	Required	Description
--project-id	string (UUID)	yes	Owning Project UUID the Node belongs to.

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 row(s) were rendered to stdout.
1	Transport or API failure, a 5xx, or — for get — no capability row visible for the requested Node.
2	Malformed --project-id / <node-id> UUID, a missing required --project-id, or an unknown --status value.
3	Missing or insecure credentials, or a 401 Unauthorized.
4	403 Forbidden.
77	ReBAC denial (403 Forbidden with reason == "rebac_denied").

Examples

List the capability rows of a Project

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

plexctl capability list \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0

List only the drifted Nodes

plexctl capability list \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --status     drift

Drill into a single Node's capability row

plexctl capability get 0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --output     json

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml
• ../../../cmd/plexctl/commands/capability.go