hlix status

Reference for hlix status — the resolved workspace and API, the folder binding, and local-versus-cloud drift.

hlix status reports the current folder’s target and synchronization state. It shows the resolved Workspace and API, the source of each setting, the project binding and changes since the last sync.

Run it to check an unfamiliar checkout or investigate an unexpected target.

Prerequisites

Run status in any directory to inspect available configuration, including missing credentials or bindings.

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, repository, local, cloud, and install, 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
HLIX Repos  8a2b6c1d4e9f027a83b5cd6e7f80192a3b4c5d6e
local       412 files, matches the last sync
cloud       commit 8a2b6c1d4e9f027a83b5cd6e7f80192a3b4c5d6e, 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`	commit <sha> available — run `hlix pull` , `commit <sha>, up to date`, or `not checked: <error code>`
`conflict`	present only when an override contradicts the folder’s binding
`installed`	this hlix and how it was installed: `(Homebrew)`, `(npm)`, or `(installer)`
`duplicate`	present only when more than one hlix is installed: which one runs, and the one command that removes the other

A completed status report exits 0, including when it reports missing configuration, an unreachable API or a target conflict. Invalid command arguments exit 2.

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 the status report starts.
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. Local configuration and scan results remain available.
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 the hlix: block in hlix.yml to match it.