Authenticate

Authentication has two parts: a browser sign-in (or an API key, for CI) proves who you are, and a workspace ID selects the tenant the CLI is allowed to act in.

Prerequisites

• A working hlix installation
• An hlix account you can sign in to in a browser (for CI: an API key)

For CI, create an API key in Developer tools → API keys. That page also shows the active workspace ID with a copy button. A newly created key is displayed once, so save it in your password manager before closing the dialog.

Keep keys out of shell history

Use hlix auth login --api-key to enter a key at a hidden prompt or read it from stdin. Supply CI credentials through your secret store’s environment variables.

Sign in

Pick the path that matches where the command runs.

Interactive

Interactive login, on a machine with a terminal:

1. Start login.

   hlix login

   Add --workspace <workspace-id> to choose the workspace up front. hlix auth login is the same command.

2. Approve the code in your browser. The CLI prints a verification URL and a one-time code, and opens the page. Sign in to your hlix account and confirm the code shown in the terminal.

3. Choose the workspace. After verifying the sign-in, the CLI lists the workspaces you can act in. With one, it is selected automatically; with several, pick one by number.

Expected result:

Signed in to https://server.hlix.ai
Credential stored at …/hlix/credentials.json

The credential file is written with owner-only permissions. Its location follows HLIX_CONFIG_HOME, then XDG_CONFIG_HOME, then ~/.config.

CI

In CI, supply credentials through secret environment variables, then run commands directly:

export HLIX_API_KEY='…'
export HLIX_WORKSPACE_ID='<workspace-id>'
hlix projects list --json

Expected result: a JSON envelope with schemaVersion and data. HLIX_BASE_URL is optional and defaults to https://server.hlix.ai.

When HLIX_API_KEY is set, the CLI uses the environment credential instead of any saved file. That makes a CI override explicit and leaves a machine login untouched.

Other endpoint

Against another API endpoint, such as a local development server, point --base-url at it:

hlix auth login \
  --workspace <workspace-id> \
  --base-url https://api.example.com

Use HTTPS. Local development also accepts HTTP on localhost, 127.0.0.1 or ::1.

The stored credential remembers this origin, so later commands can use the endpoint without repeating the flag. A folder binding or explicit override can take precedence; hlix status shows the resolved endpoint.

Check which credential is in use

hlix auth status

Expected result:

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

The output identifies the credential source and checks access to the API and Workspace. The key is omitted.

hlix status answers the wider question — which workspace this folder resolves to, and why. See Where a command points.

Sign out

hlix auth logout

This removes the saved credential file after confirmation. In automation, pass --yes to confirm the removal.

To remove an environment credential, unset HLIX_API_KEY in the shell or secret store that supplies it:

HLIX_API_KEY is set in this environment; unset it there to sign out.

If login fails

• --workspace is required here: …: the key can act in several workspaces and the CLI could not ask. 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 the command in an interactive terminal, or set HLIX_API_KEY for CI.
• login_denied / login_expired: the code was denied in the browser, or ran out before it was approved. Run hlix login again.
• unauthenticated: the key was rejected. Rotate or replace it, then retry.
• forbidden: the key is valid, but the user cannot act in that workspace.
• invalid_base_url — --base-url must use HTTPS (HTTP is allowed only for localhost). Use TLS, or a loopback hostname for local development.
• unreachable: verify the API URL, DNS, TLS, and network path.
• workspace_mismatch: an explicit Workspace or API override conflicts with the folder binding. Check hlix status, then remove the conflicting override. You can use hlix auth login to sign in to another Workspace.
• approval_required from auth logout: the caller cannot answer a prompt. Repeat with --yes.

Next steps

Quickstart: ship your first task

Import a project, start a run, and read the diff an agent produced.

Move an existing project to hlix

The import path in full: dry run, history policy, and blockers.

CLI commands

Flags, the JSON envelope, exit codes, and environment variables.