HelixDB Docs

Reference

Manage the WorkOS login session that every Helix Cloud command uses. Cloud only; local commands never need it.

Usage

helix auth login
helix auth status
helix auth logout

Subcommand	Description
`login`	Sign in through WorkOS in your browser and store the session.
`status`	Verify the session and show the signed-in email and your workspaces by name.
`logout`	Revoke the session when possible and delete the local credential file.

Flag	Description	Default
`--json`	Print the result as JSON on stdout and never prompt. `status` prints `{"email":"...","workspaces":[{"id":"...","name":"..."}]}`.	Off

login requires an interactive terminal, so it fails with --json.
It starts WorkOS PKCE in a browser (and prints the URL in case the browser does not open), then shows a spinner while it waits for the loopback callback on http://localhost:8765/callback. The login times out after 5 minutes.
If WorkOS requires email verification, the CLI prompts for the code.
It hydrates all current workspace memberships and stores only the rotating WorkOS session in ~/.helix/credentials (or $HELIX_HOME/credentials).

The CLI refreshes tokens within 60 seconds of expiry and serializes refreshes across processes.
The credential file is mode 0600 and rejects old key fields.
Cloud commands do not accept environment API keys, service credentials, legacy user/admin keys, or custom authorization headers.

status verifies the session by listing your workspaces through the Helix Cloud API, then prints Email and Workspaces (by name).
logout asks the Helix Cloud API to revoke the session when possible and always deletes the local file.

# Sign in (opens a browser)
helix auth login

# Check who is signed in
helix auth status

# Sign out and delete the local session
helix auth logout