plexctl tcp-forward

Synopsis

plexctl tcp-forward issues a one-time mediated generic-TCP access session against a Resource, then resolves a local bind address and the on-Node listener endpoint and hands them to the local forwarder. It POSTs an IssueSession request with kind=tcp and acts locally on the resulting IssuedSession; it does not open the browser attach WebSocket.

plexctl tcp-forward --project-id <uuid> --resource-id <uuid> --host <host> --port <port> [flags]

Subcommands

plexctl tcp-forward is a single-leaf command — there are no subcommands. It performs one operation: issue the session, then run (or print) the local port-forward.

plexctl tcp-forward

POSTs /v1/projects/{project_id}/sessions with a kind=tcp body naming the target --host and --port, expecting 201 Created with an IssuedSession. plexctl then resolves the local bind address (--local-addr, defaulting to 127.0.0.1:0) and the on-Node listener endpoint and hands them to the forwarder. The default forwarder prints the resolved coordinates — the local address and the on-Node listener endpoint — rather than binding a long-lived proxy loop, so the operator wires their own tunnel client against the printed endpoint. The session token is withheld from the printed output unless --reveal-secrets is set, in which case a one-line warning is written to stderr and the invocation is audit-logged.

Every required flag is validated inside the command: an omitted or malformed --project-id / --resource-id, an empty --host, or a --port outside 1-65535 exits 2.

Flags

plexctl tcp-forward

Flag	Type	Required	Description
--project-id	string (UUID)	yes	Owning Project UUID.
--resource-id	string (UUID)	yes	Target Resource UUID.
--host	string	yes	Target host the tunnel forwards to.
--port	int	yes	Target port the tunnel forwards to (1-65535).
--local-addr	string	no	Local bind address for the forwarded port (default 127.0.0.1:0).
--ttl-seconds	int	no	Requested session TTL in seconds (server default when zero).
--reveal-secrets	bool	no	Print the one-time session token to stderr (audit-logged). Inherits the root persistent flag when unset.

Persistent flags inherited from root

--server, --profile, --token-file, --output, --reveal-secrets. 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 mediated session was issued and the local port-forward instruction was resolved.
1	Transport or API failure, a 5xx, an issued session with no listener endpoint, or a forwarder error.
2	Malformed or missing --project-id / --resource-id, an empty --host, or a --port outside 1-65535.
3	Missing or insecure credentials, a 401 Unauthorized, or a 401 step_up_required (re-authenticate before retrying).
4	403 Forbidden.
77	ReBAC denial (403 Forbidden with code == "rebac_denied").

Examples

Forward a local port to a Resource target

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

plexctl tcp-forward \
  --server      "${PLEXSPHERE_URL}" \
  --project-id  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id 0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --host        10.0.0.5 \
  --port        5432

Bind a fixed local address and reveal the token

plexctl tcp-forward \
  --server         "${PLEXSPHERE_URL}" \
  --project-id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id    0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --host           10.0.0.5 \
  --port           5432 \
  --local-addr     127.0.0.1:15432 \
  --reveal-secrets

Cross-references

• ssh.md and kubeconfig.md — the sibling mediated-session families over the same IssueSession operation.
• ../../../../api/openapi/plexsphere-v1.yaml
• ../../../../cmd/plexctl/commands/tcp_forward.go
• ../../../contexts/access.md