# hlix tasks

**`hlix tasks` reads tasks and follows their status.** All four commands are transport-only: with `--json` the body is the API's response passed through **unmodified**. None of them starts, dispatches, or cancels work.

## Prerequisites

- A credential that reaches the resolved workspace (see [`hlix auth login`](/reference/cli/auth/))
- A task ID for `get`, `review`, and `watch` — [`hlix tasks list`](#hlix-tasks-list) is where you get one

## `hlix tasks list`

```bash
hlix tasks list [--project <id>] [--status <status>] [--json]
```

### Flags

- **`--project <id>`** (`string`, default the bound project): restrict the listing to one project. With no flag, a folder bound to a project lists that project's tasks; anywhere else it lists the whole workspace's tasks. Unlike [`projects get`](/reference/cli/projects/), the unbound case is a **fallback, not an error**.
- **`--status <status>`** (`string`, default: every status): restrict to one [task status](/running/tasks/#task-statuses). The value is passed through to the API; an unrecognised one is refused there, not locally.
- **`--json`** (`boolean`, default `false`): the API's task array, unmodified.

Expected result:

```bash
hlix tasks list --status building
```

```text
ID                                    STATUS    TITLE
------------------------------------  --------  ------------------
b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90  building  Add GET /healthz
```

An empty result prints `No tasks.` and exits `0`. The `TITLE` column falls back to the first line of the description when a task has no title.

## `hlix tasks get`

```bash
hlix tasks get <task-id> [--json]
```

- **`task-id`** (`string`, **required**): omitting it exits `missing_argument`; a second positional exits `invalid_usage`.

Expected result:

```text
id           b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90
status       building
title        Add GET /healthz
project      6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
description  Return 200 with the build SHA and cover it with a test.
```

## `hlix tasks review`

```bash
hlix tasks review <task-id> [--json]
```

Returns the **verified review evidence**: the comparison the QA evaluator judged, read back from the repository host rather than summarised by the agent. See [Reviewing output](/running/review/) for the document's meaning and for leaving line-level comments.

- **`task-id`** (`string`, **required**).
- **`--json`** (`boolean`, default `false`): the envelope. Without it the human view prints the evidence as indented JSON — the published contract does not pin this body, so the CLI states what it found rather than pretending to know the shape.

## `hlix tasks watch`

```bash
hlix tasks watch <task-id> [--json]
```

Consumes the task's server-sent status stream and exits when the task reaches a terminal status or the server closes the stream.

- **`task-id`** (`string`, **required**).
- **`--json`** (`boolean`, default `false`): emit **one envelope per line** (JSONL), so a consumer can read frames as they arrive. This is the one command whose `--json` output is not a single document.

Expected result:

```text
queued
building
testing
reviewing
done
```

A frame carrying an `error` field prints `error: <message>` instead of a status. Frames whose payload is not JSON are printed verbatim.
**The stream is bounded, and closing is the only terminal signal:** The server polls every 2 seconds for at most 600 iterations, so the stream ends after roughly 20 minutes whether or not the task finished. There is no `done` event — the stream simply closes once the status reaches `done`, `failed`, `pr_created`, or `ci_passing`. Read the status field, and treat a clean exit at a non-terminal status as "reconnect", not "finished".

A missing task is a **frame, not a 404**: the stream opens `200` and sends `{"error":"Task not found"}` before closing.

### Conflicts and validation

- `watch` returns `0` when the stream closes, including a close the server initiated. Check the last status, not only the exit code.
- `list` is the only command in the group that takes command-specific flags; passing `--project` or `--status` to `get`, `review`, or `watch` exits `invalid_usage`.

## What this group does not do

- **No execution.** There is no way to start a run, execute a cycle, or dispatch a task from the CLI — dispatching from a dropped connection can duplicate work. Use the API or the dashboard; see [Cycles](/running/cycles/).
- **No `tasks logs --follow`.** The public API has a task-status stream, not a log stream, so a `--follow` here would be a poll dressed up as a stream. `tasks watch` is named for what it actually does.

## If a tasks command fails

- `missing_argument` — ``A task id is required.``
- `not_found` — no such task in this workspace. The API does not confirm cross-tenant existence; do not infer it.
- `{"error":"No review evidence: this task has no branch (it was never dispatched through a cycle)"}` — the task exists but never ran. A standalone task does not execute; see [Tasks](/running/tasks/).
- `No tasks.` immediately after starting a run — planning has not produced any yet. Wait and re-run rather than starting a second run.
- `unreachable` mid-`watch` — the connection dropped. Re-run `watch`; it re-opens from the current status.
- `unauthenticated` / `forbidden` — the credential does not reach this workspace. [`hlix auth status`](/reference/cli/auth/) probes it.

## Next steps

[Tasks](/running/tasks/)
  [Reviewing output](/running/review/)
  [hlix projects](/reference/cli/projects/)
  [CLI reference](/reference/cli/)