Skip to main content
Authentication and account management.

​
Commands

​
Login

Login accepts server, email, password, name, sso, saml, provider, 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. provider picks the browser SSO provider: oidc, saml, google or github. It implies sso, and the CLI rejects a provider the server has not enabled, or saml combined with a different provider. A bare sso uses the only enabled provider, or asks which one when the server enables several. JSON mode and non-interactive input never ask, so a bare sso there falls back to the server default (OIDC, then SAML); pass provider to choose. 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:
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:

​
Logout

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

The JSON form returns the server user object directly.

​
Status

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

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.
Passwords require at least 12 characters, one uppercase letter, one number, and one special character.

​
Set username

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

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