# hlix projects

**`hlix projects` reads the projects in the resolved workspace.** Both commands are transport-only: with `--json` the body is the API's response passed through **unmodified**, so a script never finds that the CLI dropped a field the API returned.

## Prerequisites

- A credential that reaches the resolved workspace (see [`hlix auth login`](/reference/cli/auth/))

## `hlix projects list`

```bash
hlix projects list [--json]
```

Lists every project in the workspace the [target chain](/reference/cli/#where-a-command-points) resolved. It takes no positional arguments and no command-specific flags.

Expected result:

```text
ID                                    NAME            STACK
------------------------------------  --------------  ------
6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41  acme-invoices   bun
```

An empty workspace prints `No projects.` and exits `0`.

## `hlix projects get`

```bash
hlix projects get [project-id] [--json]
```

### Arguments

- **`project-id`** (`string`, optional, default the bound project): which project to show. With no ID, the project this folder is bound to is used — found by walking **up** from `--cwd`. Outside a bound folder, omitting it exits `missing_argument`: ``A project id is required, or run this inside a folder bound to a project.``

Expected result:

```text
id      6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
name    acme-invoices
stack   bun
status  active
repos   1
```

### Conflicts and validation

- The human view selects columns and **omits empty fields**; the `--json` body does not. Read the envelope, not the table.
- A project in another workspace answers `not_found` rather than `forbidden` — the API does not confirm cross-tenant existence, and neither does the CLI.
- At most one positional argument; a second exits `invalid_usage`.

## If a projects command fails

- `unauthenticated` — ``No credential. Run `hlix auth login`, or set HLIX_API_KEY for CI.``
- `forbidden` — the key is valid but the user cannot act in the resolved workspace.
- `not_found` on `projects get` — the ID is wrong, or belongs to a workspace this key cannot see. Do not infer which.
- `workspace_mismatch` — an override contradicts the folder's binding. [`hlix status`](/reference/cli/status/) shows which source decided what.
- `missing_argument` — run it inside a bound folder, or pass the ID.
- `unreachable` — the API could not be contacted; the failure is transport, not authorization.

## Next steps

[hlix tasks](/reference/cli/tasks/)
  [Tasks](/running/tasks/)
  [hlix status](/reference/cli/status/)
  [CLI reference](/reference/cli/)