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)
• A task ID for get, review, and watch — hlix tasks list is where you get one

hlix tasks list

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, the unbound case is a fallback, not an error.
• --status <status> (string, default: every status): restrict to one task status. 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:

hlix tasks list --status building

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

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

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

Expected result:

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

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 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

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:

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.
• 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.
• 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 probes it.

Next steps

TasksEvery status, the stream's four properties, and why a standalone task does not run.

Reviewing outputWhat the evidence document contains, and how to comment and request a revision.

hlix projectsFind the project a task belongs to, and the bound-folder default.

CLI referenceThe JSON envelope, JSONL streams, and every error code above.