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.

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

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:

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

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:

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

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

AuthenticateThe walkthrough: interactive login, CI variables, and self-hosted endpoints.

hlix statusWhich workspace this folder resolves to, and which source decided.

CLI referenceThe target chain, the JSON envelope, and every error code.

Secrets & protected filesWhere credentials live and how they reach a Coding Workspace.