plexctl ssh

Synopsis

plexctl ssh issues a one-time mediated SSH access session against a Resource, waits for the target Node to report the session's on-Node listener endpoint, then execs the local ssh client against that endpoint. It POSTs an IssueSession request with kind=ssh, reads the session projection until the endpoint is reported, and acts locally on the result; it does not open the browser attach WebSocket.

plexctl ssh --project-id <uuid> --resource-id <uuid> --login-user <user> [flags]

Subcommands

plexctl ssh is a single-leaf command — there are no subcommands. It performs one operation: issue the session, then exec the local ssh client.

plexctl ssh

POSTs /v1/projects/{project_id}/sessions with a kind=ssh body and the requested login user, expecting 201 Created with an IssuedSession. The listener endpoint settles asynchronously (the target Node reports it after issuance), so plexctl reads GET /v1/projects/{project_id}/sessions/{session_id} and repeats that read every two seconds until the session carries a listener_endpoint or --listener-timeout elapses. A transport failure or a 5xx on one of those reads is retried on the next tick rather than ending the wait, and surfaces only if it is still failing when the timeout elapses; a 4xx ends the wait at once. It then builds the argv ssh <listener_endpoint> and execs the local ssh binary, handing the one-time JWT to that client through the PLEXCTL_SESSION_TOKEN environment variable so the token never appears on the process table (ps / /proc). The token is not printed unless --reveal-secrets is set, in which case a one-line warning is written to stderr and the invocation is audit-logged.

--project-id and --resource-id are parsed as UUIDs locally; --login-user is required and an empty value exits 2. When the local ssh client is absent from PATH the command exits 2 with a "local ssh client not found" message.

Flags

plexctl ssh

Flag	Type	Required	Description
--project-id	string (UUID)	yes	Owning Project UUID.
--resource-id	string (UUID)	yes	Target Resource UUID.
--login-user	string	yes	SSH login user the mediated session connects as.
--ttl-seconds	int	no	Requested session TTL in seconds (server default when zero).
--listener-timeout	duration	no	How long to wait for the target Node to report the session's listener endpoint (default 1m0s). 0 reads the session exactly once and fails if the endpoint is absent.
--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 ssh client exited successfully.
1	Transport or API failure, a 5xx, a target Node that reported no listener endpoint before --listener-timeout elapsed, or a non-missing-binary ssh exec error.
2	Malformed --project-id / --resource-id UUID, a missing required flag, or the local ssh client is absent from PATH.
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

Open a mediated SSH session as a login user

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

plexctl ssh \
  --server      "${PLEXSPHERE_URL}" \
  --project-id  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id 0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --login-user  ops

Open a session with a bounded TTL and reveal the token

plexctl ssh \
  --server         "${PLEXSPHERE_URL}" \
  --project-id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id    0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --login-user     ops \
  --ttl-seconds    900 \
  --reveal-secrets

Cross-references

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