hlix tasks

hlix tasks lets you inspect tasks, follow their status, and add checklist items. Use --json for the API response in the CLI envelope.

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 create

hlix tasks create <project-id> --description <brief> [--title <title>] [--json]

Adds a task to the project’s board. It does not dispatch the task. To request implementation, submit a request for a cycle with hlix cycles create <project-id> --title <title> --description <brief>; the project plans its tasks and starts the work.

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.
• --status <status> (string, default: every status): restrict to one task status. Use one of the documented status values.
• --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]

Prints the verified review evidence of the task’s cycle. A task is a checklist item of its cycle and has no branch of its own, so the command reads the cycle’s change (GET /v1/api/cycles/:id/review): the cycle branch compared with the commit it was cut from. A task that belongs to no cycle exits with not_found. See Reviewing output.

• task-id (string, required).
• --json (boolean, default false): the envelope. Without it, the human view prints the evidence as indented JSON.

hlix tasks watch

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

Prints the task’s status each time it changes and exits when the task is over: finished, or left unfinished by a cycle that ended — printed as an error: line saying why.

• task-id (string, required).
• --json (boolean, default false): emit one envelope per line (JSONL), so a consumer can read changes as they arrive. Each data is { state, task, reason? }, where state is running, finished or unmet. Project watches and other continuous commands also use JSONL.

Expected result:

queued
building
done

A frame carrying an error field prints error: <message>.

A task watch reads the project’s live state and reconnects with backoff after a dropped connection. It ends when the task reaches a final status and its cycle settles, or when the cycle ends before the task completes (state: "unmet"). A task that review sent back can still be retried while its cycle is active, so failed alone does not end the watch.

Conflicts and validation

• watch returns 0 after its terminal result, including unmet. Check the final state and task status to determine whether the work succeeded.
• --project and --status apply to list; passing either to get, review or watch exits invalid_usage.

If a tasks command fails

• missing_argument — A task id is required.
• not_found — check the task ID, selected Workspace and your project access.
• Task <id> belongs to no cycle, so there is no change to review. — the task has no cycle-level change. 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

Tasks

Task statuses and progress within a cycle.

Reviewing output

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

hlix projects

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

CLI reference

The JSON envelope, JSONL streams, and every error code above.