> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/auth.md). # 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 ```bash 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: ```bash 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: ```bash observal auth login --sso --output json ``` ## Logout ```bash 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 ```bash observal auth whoami observal auth whoami --output json ``` The JSON form returns the server user object directly. ## Status ```bash 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 ```bash 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. ```bash 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 ```bash 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](/reference/environment-variables.md). ## Related * [`observal config`](/cli-reference/config.md): local configuration * [Self-hosting authentication](/self-hosting/authentication.md): server authentication and SSO --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.observal.io/cli-reference/auth.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.