Auth & Doctor

Auth, session, and diagnostic commands. These are top-level commands (not subgrouped) because they apply to the CLI as a whole rather than a single domain.

Authentication

The CLI authenticates against the OptimalOS Supabase instance using email + password. Credentials are stored in ~/.optimal/credentials.json (or the equivalent path returned by the credentials helper).

optimal login

Sign in interactively. Prompts for email and password, exchanges them for a session token, and writes the token to the credentials file.

optimal login

If you are already logged in, the existing session is overwritten. Use optimal logout first if you want to be explicit.

optimal signup

Create a new account. Prompts for email, password, and (optionally) display name; creates the user in Supabase auth and writes the resulting session token.

optimal signup

To verify: signup may be gated by Supabase's email-confirmation flow depending on the project settings. If the CLI returns a "check your email" message, confirm before running other commands.

optimal logout

Clear the stored credentials. Subsequent commands will fail with an auth error until you log back in.

optimal logout

Sessions

optimal session list

List active terminal sessions associated with the current user. Useful for spotting orphaned sessions across compute nodes.

optimal session list

The exact column set depends on the Supabase view backing the command; expect at minimum session id, host, agent, started-at, and status.

Diagnostics

optimal doctor

Full system health check. Validates the local environment, confirms required environment variables are set, checks Supabase connectivity (both OptimalOS and ReturnPro instances), reports the current instance heartbeat status, and surfaces any configuration issues.

# Read-only health check
optimal doctor

# Auto-fix discovered issues (install cron, register instance, etc.)
optimal doctor --fix

# Explicitly name the instance (defaults to hostname)
optimal doctor --fix --name pop-os

Flag	Description
--fix	Auto-fix issues. Currently includes installing the cron entry for optimal infra heartbeat and registering the instance in openclaw_instances.
--name	Instance name to register / heartbeat as. Defaults to the machine's hostname.

Exit code is 0 on a clean bill of health and non-zero when the doctor identifies a problem it could not (or would not, without --fix) repair.