plexctl whoami

Synopsis

plexctl whoami calls GET /v1/auth/whoami against the resolved plexsphere control plane using the configured bearer token and prints the principal the server resolved that token to. The command is the canonical sanity check after plexctl login: a successful call proves the persisted token reaches the API, the Authorization header is accepted, and the server can map it onto a Whoami projection (subject, principal_type, principal_scope, domain_id, acr, amr).

The principal_scope discriminator distinguishes a tenant token (domain, with domain_id set) from a Domain-independent platform-operator token (platform, with domain_id omitted — the token minted by plexctl login --platform). The text table echoes it in a SCOPE column; a platform principal renders DOMAIN as - and never shows a zero UUID as if it were a tenant.

The output respects the persistent --output flag — text yields a tab-aligned table; json and yaml emit the typed Whoami payload verbatim so a CI script can scrape e.g. principal_scope without post-processing.

Invocation

plexctl whoami [persistent flags]

The command takes no positional arguments and no command-specific flags. Behaviour is fully driven by the resolved profile + persistent flag bag.

Flags

whoami declares no command-specific flags. Every parameter the command consumes is inherited from the root command.

Persistent flags inherited from root

Flag	Type	Required	Default	Description
--server	string	conditional	profile / PLEXSPHERE_URL	API URL (https://host:port). Required when no profile is configured and PLEXSPHERE_URL is unset.
--profile	string	no	file-level default	Named profile from the plexctl config file.
--token-file	path	conditional	profile / PLEXSPHERE_TOKEN	Bearer token file (mode 0600). Required when no profile is configured and PLEXSPHERE_TOKEN is unset.
--output	enum	no	text	Output format: text | json | yaml.
--yes	bool	no	false	Inert for whoami (no destructive operation).
--reveal-secrets	bool	no	false	Inert for whoami (no secret payload).

See plexctl.md for the canonical persistent-flag contract and the precedence chain enforced by profile.Resolve.

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 server returned 200 OK and the typed Whoami payload was rendered.
1	yes	Runtime / API error: transport failure, non-200 status that is neither 401 nor 403, or a malformed response body.
2	yes	Flag-parse / misconfiguration: unknown --output format or a typo on a persistent flag.
3	yes	Missing or insecure credentials: profile.ErrNoServer / profile.ErrNoToken, or 401 Unauthorized from the API mapped through output.DecodeProblem.
4	yes	Permission denied: 403 Forbidden from the API.
64	no	Not reachable — whoami is fully implemented and never returns *NotImplementedError.

Examples

Happy path

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

plexctl whoami --server "${PLEXSPHERE_URL}"

PRINCIPAL  SCOPE   SUBJECT                               DOMAIN                                ACR  AMR
user       domain  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0  -    -

Platform-scoped token (after plexctl login --platform)

plexctl whoami --server "${PLEXSPHERE_URL}"

PRINCIPAL  SCOPE     SUBJECT                               DOMAIN  ACR  AMR
user       platform  0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1  -       -    -

A platform-operator token belongs to no tenant Domain: the SCOPE column reads platform and the DOMAIN column stays -. The JSON payload carries "principal_scope": "platform" with the domain_id key absent:

{
  "principal_type": "user",
  "principal_scope": "platform",
  "subject": "0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1"
}

JSON for scripting

plexctl whoami --server "${PLEXSPHERE_URL}" --output json

{
  "principal_type": "user",
  "principal_scope": "domain",
  "subject": "0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1",
  "domain_id": "0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0"
}

Missing credentials (exit 3)

unset PLEXSPHERE_TOKEN
plexctl whoami --server "${PLEXSPHERE_URL}"
# stderr: no token available (set --token-file, PLEXSPHERE_TOKEN, or run 'plexctl login')
echo $?  # 3

profile.Resolve surfaces ErrNoToken before any HTTP request leaves the CLI; the dispatcher routes it to exit 3 per the shared exit-code taxonomy.

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml — GetAuthWhoami (/v1/auth/whoami) operation definition and the Whoami schema.
• ../../contexts/identity/idp.md — bounded-context reference describing the principal resolution the whoami response projects.
• ../../../cmd/plexctl/commands/whoami.go — source of truth for the cobra command, table projection, and the format-dispatch contract.