Install and authentication

Install and first login are on the Install page. This page covers sessions, profiles and workspace selection after that.

Sessions

pier login stores an opaque session token per profile, one profile per controller URL. The default profile is default; pier login <url> --profile <name> adds another. Tokens expire after 30 days; running pier login again renews the token.

pier whoami                       # user, workspace, profile
pier profiles                     # every profile; * marks the default
pier profiles use internal        # switch the default
PIER_PROFILE=internal pier ls     # one shell, no switch
pier --profile internal ls        # one command
pier logout                       # this profile's session only

Workspace

A session belongs to one user, who may be a member of several workspaces. The workspace a command acts in is, in order: -w <name>, then the workspace saved by pier workspaces use, then the only workspace the user has. Roles are owner > admin > developer > viewer; a command that needs more than the session's role fails with 403 and says which role it needs.

The login helper

pier login also starts pier agent, a localhost endpoint the web console uses to detect an installed, logged-in CLI. pier logout and pier uninstall stop it. Set PIER_NO_AGENT=1 to never start it (CI, containers).

Registry credentials

Client-side builds and docker push registry.pier.run/… authenticate through the Docker credential helper the installer registers (docker-credential-pier). It answers with the current session; no separate registry login exists.