Reference
Manage the WorkOS login session that every Helix Cloud command uses. Cloud only; local commands
never need it.
Usage
Subcommands
Login methods
Options
Behavior
Login
loginneeds a terminal on stdin and stderr, so it fails with--json, in CI, or with piped input (logging in needs an interactive terminal). There is no unattended mode; see Run in CI.- Browser methods start WorkOS PKCE in a browser (and print the URL in case the browser does not open), then show a spinner while they wait for the loopback callback on
http://localhost:8765/callback. The CLI listens on127.0.0.1:8765, a fixed port registered with WorkOS; if another program holds it, login fails withbind the WorkOS callback listener on port 8765. The login times out after 5 minutes. passwordsigns in with an existing account. To create an account or reset a password, use the sign-in page. It runs only when Helix Cloud is reached over HTTPS or on this machine, so a password never travels unencrypted; with a plainhttp://CLOUD_AUTHORITYit fails withrefusing to send a password over an unencrypted connection. Browser methods are not affected.- A login request that gets no answer fails after 60 seconds. During email verification, the CLI asks for the code again instead.
--quietstill prints what a login needs: the URL, why a code prompt repeats, and the notice before single sign-on opens a second tab.- If your company requires single sign-on, any method continues through its identity provider in the browser.
- If WorkOS requires email verification, the CLI prompts for the code and accepts up to three attempts.
- It hydrates all current workspace memberships and stores only the rotating WorkOS session in
~/.helix/credentials(or$HELIX_HOME/credentials).
Log in over SSH
On a remote machine, a browser method’s callback must reach the remote CLI on port 8765. Forward that port when you connect, then open the printed URL in your local browser:helix auth login password needs no callback, so it
also works over SSH without forwarding, unless your account must use single sign-on, which continues
in the browser.
Session handling
- The CLI refreshes tokens within 60 seconds of expiry and serializes refreshes across processes.
- The credential file is mode
0600and rejects old key fields. - Cloud commands do not accept environment API keys, service credentials, legacy user/admin keys, or custom authorization headers.
Status and logout
statusverifies the session by listing your workspaces through the Helix Cloud API, then printsEmail, the number ofWorkspaces, and a table of their names and IDs, sorted by name.logoutasks the Helix Cloud API to revoke the session when possible and always deletes the local file.
Examples
Related
- CLI configuration — where the session file lives.
helix workspace— list the workspaces your session can access.- Helix Cloud workflow — end-to-end Cloud usage.