# hlix auth

**`hlix auth` manages the credential this machine uses.** An API key proves who you are; the workspace ID selects the tenant the key is used against. The two are stored together, and every other command resolves them through the [target chain](/reference/cli/#where-a-command-points).

## Prerequisites

- An hlix API key and a workspace ID you can access
- Network reach to the API you are signing in to

## `hlix auth login`

```bash
hlix auth login --workspace <id> [--base-url <https-url>] [--json]
```

Verifies a key against a real API call, then writes it atomically to the credential file with owner-only permissions. The key is never echoed and never printed back.

### Flags

- **`--workspace <id>`** (`string`, **required**): the workspace (organization) ID this credential acts in. Falls back to `HLIX_WORKSPACE_ID`. Required because an API key authenticates a *user* and names no workspace, so the caller must state one. Omitting both exits `missing_argument`.
- **`--base-url <url>`** (`string`, default `https://server.hlix.ai`, or `HLIX_BASE_URL`): the API to sign in to. Must be HTTPS; plain HTTP is accepted only for `localhost`, `127.0.0.1`, and `::1`. Anything else exits `invalid_base_url`.
- **`--json`** (`boolean`, default `false`): print the envelope instead of the human lines. The payload carries `baseUrl`, `organizationId`, and `credentialPath` — **never the key, not even a prefix**, because machine output gets piped into logs.

The key itself is read from a hidden prompt, or from `HLIX_API_KEY` when set. There is no flag for it.

Expected result:

```text
Signed in to https://server.hlix.ai
Credential stored at /Users/you/.config/hlix/credentials.json
```

### Conflicts and validation

- `login` is deliberately **outside** the target chain, so signing in to a second workspace from inside a folder bound to a different one works. Every other command refuses that contradiction with `workspace_mismatch`.
- The key is probed with a real `projects.list` call **before** anything is written, with retries disabled. A key that does not work is never stored — a stored credential that fails later, somewhere else, is worse than no credential.
- No prompt and no `HLIX_API_KEY` exits `missing_credential`, not an empty-string login.

## `hlix auth status`

```bash
hlix auth status [--json]
```

Names the credential's **source** — the environment or the stored file — and probes it against the API.

### Flags

- **`--json`** (`boolean`, default `false`): returns `credentialSource`, `credentialPath` (`null` for an environment credential), `baseUrl`, `baseUrlSource`, `workspaceId`, `workspaceSource`, and `valid`.

Expected result:

```text
credential  file (/Users/you/.config/hlix/credentials.json)
api         https://server.hlix.ai (from credential)
workspace   org_2p9xk4 (from credential)
status      valid
```

### Conflicts and validation

- A folder whose binding is contradicted reports `workspace_mismatch` **before** the credential is even considered, so the diagnosis does not change with an unrelated variable.
- When the probe fails, the failure is re-raised **unchanged** — the envelope's `code` and HTTP `status` match what every other command would return for the same key. The context goes to stderr: `credential from file, workspace org_2p9xk4, api https://server.hlix.ai`.
- It never prints the key, not even a prefix.

## `hlix auth logout`

```bash
hlix auth logout [--yes] [--json]
```

Removes the credential **file**. It does not, and cannot, unset an environment variable.

### Flags

- **`--yes`** (`boolean`, default `false`): skip the confirmation prompt. Without it, an interactive run asks; a `--json` or non-interactive run exits `approval_required` rather than defaulting to yes.
- **`--json`** (`boolean`, default `false`): returns `{ removed, path }`, or `{ removed: false, reason: "environment", path }` when an environment credential is in play.

### Conflicts and validation

- With `HLIX_API_KEY` set, logout reports it and leaves it alone — it belongs to the shell that set it: `HLIX_API_KEY is set in this environment; unset it there to sign out.`
- With `HLIX_API_KEY` set **and** a file underneath it, the file is named and left in place until `--yes` is passed. Removing it silently would have made `logout` a permanent no-op for anyone who had exported the variable: the stored key stayed on disk, unmentioned, and came back the moment the variable went away.
- With nothing stored, it is a successful no-op: `No stored credential at …`.
- It refuses any path that is not a credential document this CLI wrote.

## If auth fails

- `missing_argument` — ``--workspace is required.`` Pass the ID or set `HLIX_WORKSPACE_ID`.
- `missing_credential` — ``No API key entered. Run from a terminal or set HLIX_API_KEY for CI.`` Run interactively, or set the variable for CI.
- `invalid_base_url` — ``--base-url must use HTTPS (HTTP is allowed only for localhost).``
- `unauthenticated` — the key was rejected. Rotate or replace it.
- `forbidden` — the key is valid, but the user cannot act in that workspace.
- `unreachable` — check the API URL, DNS, TLS, and network path.
- `approval_required` from `auth logout` — the caller cannot answer a prompt. Repeat with `--yes`.

## Next steps

[Authenticate](/getting-started/authentication/)
  [hlix status](/reference/cli/status/)
  [CLI reference](/reference/cli/)
  [Secrets & protected files](/security/secrets/)