plexctl ssh

Synopsis

plexctl ssh issues a one-time mediated SSH access session against a Resource, then execs the local ssh client against the on-Node listener endpoint the control plane returns. It POSTs an IssueSession request with kind=ssh and acts locally on the resulting IssuedSession; 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. plexctl 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).
--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, an issued session with no listener endpoint, 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