plexctl session

Synopsis

plexctl session is the CLI surface for the per-Project mediated access Session aggregate. It wraps the read and revoke operations of /v1/projects/{project_id}/sessions — ListSessions, GetSession, and RevokeSession — so an operator can enumerate, inspect, and terminate the active ssh / k8s / tcp sessions a Project's Identities hold against its Resources.

Sessions are issued through the kind-specific kubeconfig, ssh, and tcp-forward commands, because a Session always targets a concrete Resource by kind and the signed token is delivered exactly once at issuance. This command covers the remainder of the lifecycle: the metadata-only reads and the operator revoke. The list and get projections carry metadata only — identity, scope, status, timestamps, the jti, and the signing-key id — and never the signed token.

For the bounded-context reference (the Session aggregate, the issuance state machine, the JWT claim set, and the audit relations) see ../../contexts/access.md. For the HTTP surface see ../../reference/api/access.md.

Invocation

plexctl session <subcommand> [flags]

plexctl session list

Pages the per-Project session roster via keyset cursor, optionally narrowed by --status (active|expired|revoked), --kind (ssh|k8s|tcp), or --identity-id. The CLI projects the columns ID, KIND, STATUS, IDENTITY, RESOURCE, ISSUED_AT, EXPIRES_AT.

plexctl session get

Returns the metadata view of a single Session by --session-id — useful for confirming a Session is still active or has been revoked.

plexctl session revoke

Terminates a live Session. The server fans the revocation out over the Signed Event Bus so the target plexd tears the listener down, and answers 204 on both a fresh revocation and an idempotent re-revoke. The --reason flag accepts only the operator-driven values (operator_request, the default; policy_violation; identity_compromise; resource_decommissioned) — the sweeper-only reasons (idle_timeout, ttl_expired) are set internally and rejected client-side.

Authorization

list and get require the owning Project's read permission; revoke requires its act permission. A Project read principal — for example a Platform Operator who observes a Project but holds no act authority — may list and read its Sessions without being able to revoke one. The CLI does not re-check authorization locally; it relays the server's decision, mapping a 403 Forbidden to exit code 4.

Flags

Subcommand	Flag	Required	Notes
list / get / revoke	--project	yes	Owning Project UUID.
list	--status	no	Lifecycle filter: active, expired, or revoked.
list	--kind	no	Kind filter: ssh, k8s, or tcp.
list	--identity-id	no	Restrict to Sessions issued to this Identity UUID.
list	--limit	no	Maximum items per page; server default when zero.
list	--cursor	no	Continuation token returned by a previous call's next_cursor.
get / revoke	--session-id	yes	Session UUID.
revoke	--reason	no	Operator revoke reason; defaults to operator_request.

Exit codes

Code	Reachable	Meaning
0	yes	The API returned the expected status (200 for list / get, 204 for revoke).
1	yes	Runtime / API error: transport failure, unexpected status code, or a malformed response body.
2	yes	Flag-parse / misconfiguration: missing required flag, malformed UUID, or an out-of-enum --status / --kind / --reason.
3	yes	Missing or insecure credentials, or 401 Unauthorized from the API.
4	yes	404 Not Found — get / revoke addressed a Session that does not exist in the named Project (the surface answers 404 rather than confirming a cross-Project Session).
77	yes	Permission denied: 403 Forbidden ReBAC denial (the caller lacks project:read for list / get, or project:act for revoke).
64	no	Not reachable — session is fully implemented and never returns *NotImplementedError.

Examples

List the active ssh sessions in a Project:

plexctl session list --project "$PROJECT_ID" --status active --kind ssh

Inspect one Session:

plexctl session get --project "$PROJECT_ID" --session-id "$SESSION_ID"

Revoke a Session with an explicit reason:

plexctl session revoke --project "$PROJECT_ID" --session-id "$SESSION_ID" \
  --reason policy_violation