plexctl logout

Synopsis

plexctl logout ends the active session — the counterpart to plexctl login. It revokes the session's bearer token server-side via DELETE /v1/auth/tokens/{id} so the token stops authenticating, then removes the stored credential from the plexctl config file. The id is recovered from the stored token itself, so logout is a single round trip with no prior list call.

Logout acts only on the currently active session — the profile named by --profile, or the file-level default pointer when --profile is omitted — not on every stored profile. Revocation runs before the local credential is cleared; on a hard server failure the local credential is kept so the operator can retry, because a token that is still live must not be silently forgotten.

When no active session exists the command is a clean no-op: it prints a short note to stderr and exits 0.

Invocation

plexctl logout [--profile <name>] [persistent flags]

The command takes no positional arguments. With no --profile, logout operates on the file-level default profile.

Flags

plexctl logout declares no local flags. It reads the --profile persistent flag to select which stored session to end; see plexctl.md for the canonical list of persistent flags (--server, --profile, --token-file, --output, --yes, --reveal-secrets).

The --token-file and PLEXSPHERE_TOKEN credential sources are not acted on by logout: it operates on the on-disk profile entry, the only credential plexctl manages. A token injected purely through the environment or a file surfaces as "no active session".

Exit codes

plexctl collapses every failure into the taxonomy below; the single source of truth is exitCodeFor in ../../../cmd/plexctl/app.go.

Code	Reachable	Meaning
0	yes	The session was revoked and the local credential cleared, or there was no active session to end (clean no-op). A server 401/404 is also success — the session is already gone — so the local credential is cleared.
1	yes	Runtime / API error: transport failure reaching the server, or a 5xx response. The local credential is preserved so the operator can retry.
2	yes	The stored token is not a recognizable session token, so its id cannot be derived and the session cannot be revoked. The local credential is preserved.
3	rare	The config file mode is wider than 0600 — the credential file is refused before it is read (the same 0600 contract login writes under).
4	rare	Permission denied (403) when revoking the token. The local credential is preserved.
64	no	Not reachable — logout is fully implemented and never returns *NotImplementedError.

Examples

End the active session

plexctl logout
# stdout: Logged out. Cleared profile "default".
echo $?  # 0

The CLI derives the token id from the stored credential, issues the DELETE /v1/auth/tokens/{id} revocation, and removes the default profile entry (resetting the file-level default pointer).

End a specific profile's session

plexctl --profile staging logout
# stdout: Logged out. Cleared profile "staging".

Only the staging entry is revoked and removed; other stored profiles and the default pointer are left untouched unless staging was the default.

No active session (no-op)

plexctl logout
# stderr: No active session; nothing to do.
echo $?  # 0

With no config file, no matching profile, or a profile carrying no token, logout makes no server call and exits 0.

JSON summary for CI scripts

plexctl logout --output json

In json / yaml mode a structured summary is emitted on success:

{
  "profile": "default",
  "server": "https://localhost:8080",
  "revoked": true
}

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml — DeleteAuthTokenByID (DELETE /v1/auth/tokens/{id}) operation definition; logout revokes the active session through it.
• ../../../cmd/plexctl/commands/logout.go — source of truth for the cobra command, the revoke-before-clear ordering, and the no-active-session no-op.
• ../../../cmd/plexctl/internal/auth/token.go — recovers the API token aggregate id embedded in the stored psk plaintext so logout can address the DELETE without a list call.
• login.md — the counterpart command that establishes the session logout ends.