observal auth

Authentication and account management.

Commands

Command	Description
observal auth login	Authenticate with credentials or browser SSO
observal auth logout	Revoke the remote session when possible and clear local credentials
observal auth whoami	Show the authenticated user
observal auth status	Check authenticated server and local outbox health
observal auth change-password	Change the current user's password
observal auth set-username	Set or update the registry namespace username

Login

observal auth login
observal auth login --server https://observal.example.com --email alice
observal auth login --sso

Login accepts server, email, password, name, sso, saml, output, and no-setup options. Prefer OBSERVAL_PASSWORD or OBSERVAL_PASSWORD_FILE over the password option so the secret does not enter shell history or process arguments.

Human login always asks for the server URL unless --server is supplied; leave the prompt blank to use http://localhost. On a fresh server, provide email, name, and a password to create the first administrator. JSON mode never prompts, uses the configured server or local default, and requires complete credential inputs.

Successful human login synchronizes the bundled skills, creates the initial layer snapshot, and runs doctor. Select no-setup to skip the snapshot and doctor. JSON mode skips those post-login steps.

Every CLI invocation also computes a SHA-256 hash for each installed Observal-managed skill tree. A mismatched tree is replaced completely from the packaged bundle, including references and scripts, so local edits and stale extra files do not survive. Skill directories outside the six bundled Observal names are untouched.

Credential JSON login emits one safe object and never includes tokens or passwords:

OBSERVAL_PASSWORD_FILE=/run/secrets/observal-password \
  observal auth login \
  --server https://observal.example.com \
  --email alice \
  --output json

Browser SSO in JSON mode is a JSON Lines stream. The first event contains the verification URL and user code. The final event confirms authentication:

observal auth login --sso --output json

Logout

observal auth logout
observal auth logout --output json

Logout always removes local tokens when the local configuration is readable. Remote revocation is best effort and is reported separately in JSON. Use observal doctor cleanup to remove Observal-managed harness hooks.

Current user

observal auth whoami
observal auth whoami --output json

The JSON form returns the server user object directly.

Status

observal auth status
observal auth status --output json

Status reports the server URL, authentication state, health latency, and local telemetry outbox. It returns exit code 3 when authentication is absent and exit code 9 when the configured server is unreachable.

Change password

observal auth change-password

Both modes read OBSERVAL_CURRENT_PASSWORD and OBSERVAL_NEW_PASSWORD, including their corresponding _FILE forms. Human mode prompts for missing values; JSON mode requires both values and never prompts.

OBSERVAL_CURRENT_PASSWORD_FILE=/run/secrets/current-password \
OBSERVAL_NEW_PASSWORD_FILE=/run/secrets/new-password \
  observal auth change-password --output json

Passwords require at least 12 characters, one uppercase letter, one number, and one special character.

Set username

observal auth set-username alice
observal auth set-username alice --output json

The username is the user's registry namespace. It must follow the namespace rules shown by command help. The server prevents changes that conflict with another namespace or published registry ownership.

Environment variables

Variable	Purpose
OBSERVAL_SERVER_URL	Default server URL
OBSERVAL_ACCESS_TOKEN	Pre-authenticate commands without login
OBSERVAL_PASSWORD	Credential or bootstrap login password
OBSERVAL_CURRENT_PASSWORD	Current password for JSON password changes
OBSERVAL_NEW_PASSWORD	New password for JSON password changes and mandatory login changes
OBSERVAL_TIMEOUT	Authenticated client timeout

Password and token variables support a corresponding _FILE form. Do not set a direct value and its file form together.

Full list: Environment variables.

Related

• observal config: local configuration
• Self-hosting authentication: server authentication and SSO