plexctl bridge

Synopsis

plexctl bridge is the operator surface for the per-Resource Bridge Orchestrator. It wraps the four bridge sub-aggregate surfaces under a single cobra parent, all rooted at /v1/projects/{project_id}/resources/{resource_id}/bridge and addressed by the required --project-id / --resource-id pair on every leaf:

• …/bridge/relay — the per-Resource relay singleton (get / configure).
• …/bridge/user-access — the user-access providers (list / get / create / update / delete).
• …/bridge/ingress — the public-ingress rules (list / get / create / update / delete).
• …/bridge/site-to-site — the site-to-site tunnels (list / get / create / update / delete).

plexctl bridge relay <get|configure> --project-id <uuid> --resource-id <uuid> [flags]
plexctl bridge user-access <list|get|create|update|delete> --project-id <uuid> --resource-id <uuid> [flags]
plexctl bridge ingress <list|get|create|update|delete> --project-id <uuid> --resource-id <uuid> [flags]
plexctl bridge site-to-site <list|get|create|update|delete> --project-id <uuid> --resource-id <uuid> [flags]

Subcommands

plexctl bridge relay get

GETs …/bridge/relay. Reads the relay singleton for the Resource.

plexctl bridge relay configure

PUTs …/bridge/relay. Replaces the relay singleton wholesale. Requires --listen-port; --enabled toggles whether the relay is active.

plexctl bridge user-access list

GETs …/bridge/user-access. Lists the user-access providers of the Resource.

plexctl bridge user-access get <slug>

GETs …/bridge/user-access/{slug}. The slug is the positional argument.

plexctl bridge user-access create

POSTs …/bridge/user-access. Creates a provider keyed by --slug.

plexctl bridge user-access update <slug>

PATCHes …/bridge/user-access/{slug}. Full-replacement update — the whole provider configuration is replaced; the slug is the positional argument and is not carried in the body.

plexctl bridge user-access delete <slug>

DELETEs …/bridge/user-access/{slug}. Requires the persistent --yes flag. The slug is the positional argument.

plexctl bridge ingress list

GETs …/bridge/ingress. Lists the public-ingress rules of the Resource.

plexctl bridge ingress get <slug>

GETs …/bridge/ingress/{slug}. The slug is the positional argument.

plexctl bridge ingress create

POSTs …/bridge/ingress. Creates a rule keyed by --slug.

plexctl bridge ingress update <slug>

PATCHes …/bridge/ingress/{slug}. Full-replacement update; the slug is the positional argument and is not carried in the body.

plexctl bridge ingress delete <slug>

DELETEs …/bridge/ingress/{slug}. Requires the persistent --yes flag. The slug is the positional argument.

plexctl bridge site-to-site list

GETs …/bridge/site-to-site. Lists the site-to-site tunnels of the Resource.

plexctl bridge site-to-site get <slug>

GETs …/bridge/site-to-site/{slug}. The slug is the positional argument.

plexctl bridge site-to-site create

POSTs …/bridge/site-to-site. Creates a tunnel keyed by --slug.

plexctl bridge site-to-site update <slug>

PATCHes …/bridge/site-to-site/{slug}. Full-replacement update; the slug is the positional argument and is not carried in the body.

plexctl bridge site-to-site delete <slug>

DELETEs …/bridge/site-to-site/{slug}. Requires the persistent --yes flag. The slug is the positional argument.

Flags

Every bridge leaf requires --project-id and --resource-id. Both are UUIDs; a malformed value exits 2 before any request is sent. The tables below document only the per-leaf body flags that carry non-trivial input.

plexctl bridge relay configure

Flag	Type	Required	Description
--listen-port	int	yes	UDP port the relay listens on.
--enabled	bool	no	Whether the relay is active.

plexctl bridge user-access create

Flag	Type	Required	Description
--slug	string	yes	Stable provider identity within the Resource.
--kind	enum	yes	Provider technology: netbird | tailscale | wireguard.
--interface-name	string	yes	Network interface the provider programs.
--listen-port	int	yes	UDP port the provider listens on.
--max-peers	int	yes	Maximum number of peers the provider admits.
--auth-secret-ref	string	yes	Opaque reference to the provider's authentication material.
--routing-policy	JSON	yes	Routing-policy document as a JSON object.

plexctl bridge user-access update <slug>

Flag	Type	Required	Description
--kind	enum	yes	Provider technology: netbird | tailscale | wireguard.
--interface-name	string	yes	Network interface the provider programs.
--listen-port	int	yes	UDP port the provider listens on.
--max-peers	int	yes	Maximum number of peers the provider admits.
--auth-secret-ref	string	yes	Opaque reference to the provider's authentication material.
--routing-policy	JSON	yes	Routing-policy document as a JSON object.

plexctl bridge ingress create

Flag	Type	Required	Description
--slug	string	yes	Stable rule identity within the Resource.
--sni-host	string	yes	TLS SNI host the rule terminates.
--target-node-id	UUID	yes	Node UUID the rule forwards to.
--target-port	int	yes	TCP port on the target Node.
--acme-account-ref	string	no	Opaque reference to the ACME account used to issue the certificate.

plexctl bridge ingress update <slug>

Flag	Type	Required	Description
--sni-host	string	yes	TLS SNI host the rule terminates.
--target-node-id	UUID	yes	Node UUID the rule forwards to.
--target-port	int	yes	TCP port on the target Node.
--acme-account-ref	string	no	Opaque reference to the ACME account used to issue the certificate.

plexctl bridge site-to-site create

Flag	Type	Required	Description
--slug	string	yes	Stable tunnel identity within the Resource.
--kind	enum	yes	Tunnel technology: wireguard | ipsec | openvpn.
--remote-host	string	yes	Hostname or address of the remote tunnel endpoint.
--remote-port	int	yes	Port on the remote tunnel endpoint.
--auth-secret-ref	string	yes	Opaque reference to the tunnel's authentication material.
--allowed-subnets	[]string	yes	CIDR prefixes the tunnel routes. Repeatable and must be non-empty.
--routing-policy	enum	yes	Traffic direction: bidirectional | egress_only | ingress_only.

plexctl bridge site-to-site update <slug>

Flag	Type	Required	Description
--kind	enum	yes	Tunnel technology: wireguard | ipsec | openvpn.
--remote-host	string	yes	Hostname or address of the remote tunnel endpoint.
--remote-port	int	yes	Port on the remote tunnel endpoint.
--auth-secret-ref	string	yes	Opaque reference to the tunnel's authentication material.
--allowed-subnets	[]string	yes	CIDR prefixes the tunnel routes. Repeatable and must be non-empty.
--routing-policy	enum	yes	Traffic direction: bidirectional | egress_only | ingress_only.

Delete leaves

Flag	Type	Required	Description
--yes (persistent)	bool	yes	Required confirmation for the destructive operation.

Persistent flags inherited from root

--server, --profile, --token-file, --output, --yes, --reveal-secrets. See ../plexctl.md for the canonical list. Note that --project-id and --resource-id are required per-leaf flags, not persistent ones.

Exit codes

See ../plexctl.md#exit-code-taxonomy. Bridge domain refusals arrive as HTTP 400/409/422 and surface as exit 1; client-side flag/enum/UUID/JSON validation exits 2; a denied ReBAC relation exits 77.

Examples

Configure the relay

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

plexctl bridge relay configure \
  --server      "${PLEXSPHERE_URL}" \
  --project-id  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --resource-id 0190a8b8-b1d1-7b1b-9b1b-b1b1b1b1b1b1 \
  --listen-port 51820 \
  --enabled

Create a user-access provider

plexctl bridge user-access create \
  --server         "${PLEXSPHERE_URL}" \
  --project-id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --resource-id    0190a8b8-b1d1-7b1b-9b1b-b1b1b1b1b1b1 \
  --slug           field-ops \
  --kind           netbird \
  --interface-name wt0 \
  --listen-port    51821 \
  --max-peers      64 \
  --auth-secret-ref secret:acme/field-ops/netbird-auth \
  --routing-policy '{"advertise_routes":["10.0.0.0/16"]}'

Delete a site-to-site tunnel (requires --yes)

plexctl bridge site-to-site delete dc-east \
  --server      "${PLEXSPHERE_URL}" \
  --project-id  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --resource-id 0190a8b8-b1d1-7b1b-9b1b-b1b1b1b1b1b1 \
  --yes

Cross-references

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