# Install and authentication

> Sessions, profiles, and how a command finds its workspace

URL: https://pier.run/docs/cli/install-and-auth

Install and first login are on the [Install](/docs/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.

```bash
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.