hlix auth

hlix auth manages the credential this machine uses. A browser sign-in (or an API key) proves who you are; the workspace ID selects the tenant the credential is used against. The two are stored together, and every other command resolves them through the target chain. hlix login and hlix logout are the same commands as hlix auth login and hlix auth logout.

Prerequisites

• An hlix account you can sign in to in a browser, or an hlix API key
• Network reach to the API you are signing in to

hlix auth login

hlix login [--workspace <id>] [--base-url <https-url>] [--api-key] [--json]
hlix auth login [--workspace <id>] [--base-url <https-url>] [--api-key] [--json]

Signs in through your browser. The CLI prints a verification URL and a one-time code, opens the page, and waits for you to approve the code after signing in. The CLI verifies the login and saves it in the credential file with owner-only permissions.

Sign in to Hlix in your browser:
  https://app.hlix.ai/auth/device?user_code=WXYZ-1234
and confirm the code: WXYZ-1234
Waiting for approval…

Press Ctrl-C to stop waiting. Denying the code exits login_denied; a code nobody approves exits login_expired.

Every command that talks to the API checks for a credential before it does any work. At a terminal with none stored, it starts this same browser sign-in and then carries on. hlix import also checks that the stored credential still works before it scans the folder.

Flags

• --workspace <id> (string, optional): the workspace (organization) ID this credential acts in. Falls back to HLIX_WORKSPACE_ID. Without either, the CLI lists the workspaces the key can act in once it has verified the key: a single workspace is taken automatically, several are offered as a numbered choice. A --json or non-interactive run with several workspaces exits missing_argument naming them. A workspace the key cannot act in exits workspace_mismatch with the available IDs.

• --base-url <url> (string): the API to sign in to. Without the flag it is, in order, HLIX_BASE_URL, the API this folder’s hlix.yml is bound to (hlix.api), the API your stored credential was for, then https://server.hlix.ai; signing in again therefore goes back to the API you were using. 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; credential values are excluded.

• --api-key (boolean, default false): sign in with an API key instead of the browser. The key is read from a hidden prompt at a terminal, or from stdin when piped (printf %s "$KEY" | hlix login --api-key). Pass the key through the prompt or stdin, rather than as an argument.

With HLIX_API_KEY set, login verifies and stores that key without opening a browser.

Expected result:

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

Conflicts and validation

Login can select a new Workspace while leaving the current folder’s project binding unchanged. The CLI verifies the credential before saving it. For a non-interactive job, set HLIX_API_KEY or pipe a key to hlix auth login --api-key.

hlix auth status

hlix auth status [--json]

Names the credential’s source — the environment, the desktop app’s own login, or the stored file — and probes it against the API.

Flags

• --json (boolean, default false): returns credentialSource, credentialPath (null unless the credential came from the file), baseUrl, baseUrlSource, workspaceId, workspaceSource, and valid. credentialSource is "file" for the stored credential, "env" for HLIX_API_KEY, and "session" for the desktop app’s session — environment credentials belong to the invoking shell, while the desktop app manages its own login.

Expected result:

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 target mismatch returns workspace_mismatch. A failed credential probe returns the same API error code as other commands, with the selected Workspace and API in the diagnostic output. Credential values are excluded.

hlix auth logout

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

Removes the stored credential file. For an environment credential, clear HLIX_API_KEY in its shell; for a desktop login, sign out in the desktop app.

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 — reason: "session" when the credential is the desktop app’s.

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.
• Under the desktop app’s login it says so instead: This session belongs to the Hlix desktop app; sign out there to end it.
• With HLIX_API_KEY set and a stored file underneath it, logout identifies the saved file. Pass --yes to remove that file; the shell’s environment credential remains active.
• With nothing stored, it is a successful no-op: No stored credential at ….
• Only the CLI’s credential file is removed.

If auth fails

• missing_argument — --workspace is required here: this key can act in 3 workspaces. Pass one of: … Pass one of the listed IDs, or set HLIX_WORKSPACE_ID.
• missing_credential — A browser login needs a terminal. Set HLIX_API_KEY for CI, or pipe a key to `hlix auth login --api-key`. Run interactively, or set the variable for CI.
• login_denied — the code was denied in the browser. Run hlix login again.
• login_expired — the code ran out before it was approved. Run hlix login again.
• login_failed — the server would not start or finish the browser sign-in; the message is the server’s reason.
• 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

The walkthrough: interactive login, CI variables, and other endpoints.

hlix status

Which workspace this folder resolves to, and which source decided.

CLI reference

The target chain, the JSON envelope, and every error code.

Secrets & protected files

Where credentials live and how they reach a Cloud Machine.