> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# helix auth

> Log in to Helix Cloud, check the session, or log out

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

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

## Usage

```bash theme={null}
helix auth login
helix auth status
helix auth logout
```

## Subcommands

| 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. |

## Options

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

## Behavior

### Login

* `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`).

### Session handling

* 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 and logout

* `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.

## Examples

```bash theme={null}
# 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
```

## Related

* [CLI configuration](/cli/configuration) — where the session file lives.
* [`helix workspace`](/cli/command-reference/workspace) — list the workspaces your session can access.
* [Helix Cloud workflow](/cli/workflows/helix_cloud) — end-to-end Cloud usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.