# 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

```bash
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:

```text
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 .`](/reference/cli/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`](/reference/cli/auth/) 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 & sync](/reference/cli/sync/)
  [hlix auth](/reference/cli/auth/)
  [Push, pull & sync](/cli/sync/)
  [CLI reference](/reference/cli/)