plexctl peer

Synopsis

plexctl peer is the operator surface for inspecting the Peer Nodes anchored in a Domain's mesh. Both subcommands consume a single coherent snapshot served by GET /v1/domains/{domainId}/mesh/topology: list flattens the snapshot's Nodes onto a table; get locates a single Node id inside the same snapshot for drill-down. Running list-then-get reuses one server read and returns byte-identical Node projections.

plexctl peer list --domain <uuid>
plexctl peer get  --domain <uuid> --node <uuid>

Subcommands

plexctl peer list

GETs /v1/domains/{domainId}/mesh/topology and projects the snapshot's nodes array onto one row per anchored Node. The projection is deduplicated by NodeId before rendering so a transient re-snapshot race on the server-side projection cannot surface twice in CLI output.

plexctl peer get

GETs the same /v1/domains/{domainId}/mesh/topology snapshot and filters it to the single Node whose id matches --node. A miss is surfaced as a synthetic 404 node_not_found Problem, identical in shape to a real server-side 404 — so a CI script branching on exit code sees the same 4 either way.

Flags

plexctl peer list

Flag	Type	Required	Description
--domain	string (UUID)	yes	Domain UUID whose mesh topology to retrieve.

plexctl peer get

Flag	Type	Required	Description
--domain	string (UUID)	yes	Domain UUID whose mesh topology to retrieve.
--node	string (UUID)	yes	Node UUID to locate within the snapshot.

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 Problem.code branches that apply to this family:

HTTP status	Problem.code	Exit code
404	domain_not_found	4
404	node_not_found	4 (synthesised by peer get when the Node is absent from the snapshot)
403	rebac_denied	77

Examples

List anchored peers in a Domain

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

plexctl peer list \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0

Drill into a single peer

plexctl peer get \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --node   0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1 \
  --output json

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml
• ../../../cmd/plexctl/commands/peer.go
• ./mesh.md — sibling command rendering the directed-edge projection of the same snapshot.