hlix status

hlix status answers “where am I” in one screen: the resolved workspace and API with the source that decided each, the folder’s binding and local revision, and whether the working tree or the cloud head has moved since the last sync.

It is the first thing to type in an unfamiliar checkout, and the fastest way to find out why another command is talking to a workspace you did not expect.

Prerequisites

None. status runs in any directory, with or without a credential — reporting what is missing is part of its job.

Usage

hlix status [--cwd <dir>] [--json]

Flags

• --cwd <dir> (string, default the process working directory): report on another folder, including its binding lookup. A path that is not a directory exits invalid_usage — see the validation note below.
• --json (boolean, default false): return the structured report instead of the aligned fields. The payload carries cwd, workspace, api, credential, conflict, project, revision, local, and cloud, each with its own source or error where one applies.

Expected result:

folder      /Users/you/acme-invoices
workspace   org_2p9xk4 (from project)
api         https://server.hlix.ai (from project)
credential  file (/Users/you/.config/hlix/credentials.json)
project     6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
revision    generation 3 (rev_01J8Z4)
local       412 files, matches the last sync
cloud       generation 3, up to date

What each line can say

Line	Values you will see
workspace	the ID and its source (flag, env, project, credential), or none — run `hlix auth login --workspace <id>`
credential	environment (HLIX_API_KEY), file (<path>), or none — run `hlix auth login`
project	the project ID, initialized at <root>, not imported yet, or none — run `hlix import .` to bind this folder
local	<n> files, matches the last sync, … modified since the last sync, … no synced base revision, or could not scan: <reason>
blocking	present only when the scan found blockers; they are listed inline
cloud	generation <n> available — run `hlix pull` , generation <n>, up to date, or not checked: <error code>
conflict	present only when an override contradicts the folder’s binding

The cloud line is only attempted when the folder is bound to a project, a credential exists, and no conflict was found — so a broken login never turns into a confusing network error.

It reports; it does not judge

hlix status always exits 0. A missing credential, an unbound folder, an unreachable API and a conflicting override are each a line in the output, not a failure — a command whose job is to explain a broken setup must not fail because the setup is broken.

Conflicts and validation

• A contradicting --workspace, --base-url, or HLIX_* value appears on the conflict line rather than aborting the report. Every other command exits workspace_mismatch on the same input.
• An argument error still exits 2 — an unknown flag, a stray positional, or a --cwd that is not a directory. Those are rejected before status runs at all, which is the one exit code it cannot promise away and does not try to.
• The binding is found by walking up from --cwd, so hlix status in packages/api reports the project, not a fragment of it.

If status reports something unexpected

• workspace … (from credential) where you expected (from project) — the folder is not bound. Run hlix import ..
• cloud not checked: unreachable — the API could not be contacted. The rest of the report is still accurate; it is computed locally.
• cloud not checked: unauthenticated — the stored credential no longer works against this workspace. Run hlix auth status for the probe result.
• local could not scan: … — the scan itself failed. The message is the scanner’s own; a symlink or an unreadable path is the usual cause.
• A conflict line — drop the override rather than editing .hlix/config.json to match it.

Next steps

hlix push, pull & syncAct on the drift status just reported, including the dry-run verdicts.

hlix authWhich credential is in use, and whether it still works.

Push, pull & syncThe decision matrix behind the local and cloud lines.

CLI referenceThe target chain that produced every `(from …)` above.