plexctl mesh

Synopsis

plexctl mesh is the operator surface for inspecting the per-Domain mesh topology. The family currently exposes a single topology leaf that renders the snapshot served by GET /v1/domains/{domainId}/mesh/topology — every anchored Peer Node in a Domain together with the directed WireGuard edges between them, including the relay fallback in use when an edge is in relayed mode.

plexctl mesh topology --domain <uuid>

The same snapshot endpoint backs ./peer.md; plexctl peer projects the Nodes side, plexctl mesh topology projects the Edges side. Use whichever verb matches the question you are asking.

Subcommands

plexctl mesh topology

GETs /v1/domains/{domainId}/mesh/topology and renders the resulting MeshTopology as a flat edge table. Each row joins a directed edge to its source / target node projection so a single text / JSON / YAML payload describes both nodes and edges without requiring two round-trips. The text-mode columns are positionally stable so downstream tooling can pipe --output text through awk:

Column	Source
FROM	MeshEdge.source_node_id
TO	MeshEdge.target_node_id
MESH_IP	the target Node's mesh_ip from the Nodes lookup
FALLBACK	MeshEdge.relay_node_id (empty for direct mode)
REACH_FROM	the source Node's reachability projection
REACH_TO	the target Node's reachability projection

Flags

plexctl mesh topology

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

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
403	rebac_denied	77

Examples

Render the topology as text

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

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

Fetch the full nodes + edges JSON envelope

plexctl mesh topology \
  --server "${PLEXSPHERE_URL}" \
  --domain 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --output json

Cross-references

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