Tasks

Add a task to a cycle's checklist and watch its status until it finishes.

A task is one item on its cycle’s live checklist. The build agent works the items in order on the cycle branch in an isolated Cloud Machine. Independent cycles can run in parallel.

Prerequisites

An imported or created project — see the Quickstart
An API key and workspace ID, or a signed-in dashboard login
Agency role (owner, admin, or member) to create a task; portal clients can read and comment but not create

Where tasks come from

The project manager plans requests into cycles, then writes each cycle’s checklist. You can add a task when you already know the work that belongs to a cycle.

Creating a task

Add work to an existing cycle so it belongs to an executable checklist:

curl -sS -X POST "$HLIX_BASE_URL/v1/api/cycles/$CYCLE_ID/tasks" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"title":"Add GET /healthz","description":"Return 200 with the build SHA and cover it with a test.","dependsOn":[]}'

title and description are required. dependsOn is an optional array of task UUIDs that must finish first. The task is picked up when the cycle runs. To request a new piece of work without choosing a cycle, submit a request or send the project manager a message.

Run the cycle to execute its checklist, or let the project manager coordinate it as part of a project run.

Task statuses

A new task starts at queued. Statuses move live while the build agent works.

Status	Meaning
`queued`	On the checklist, waiting its turn
`building`	The build agent is working it now
`done`	Finished with a one-line note; review can reopen it before the cycle settles
`blocked`	The build agent could not go on and left a reason, or it waits on an unmet dependency or an unresolved approval
`failed`	Terminal for this run — the task failed

Other values the API can return belong to older work.

PATCH /v1/api/tasks/:id accepts title, description and status.

Watching a task

A task’s status is live: it changes on your screen as the work moves, with no polling.

CLI
TypeScript SDK

With the CLI:

hlix tasks watch "$TASK_ID"

Expected result — one line per status change, exiting when the task is over:

queued
building
done

--json prints 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.

With @hlix/sdk:

const task = await hlix.tasks.get(taskId)
for await (const watch of hlix.live.task(task.projectId, taskId)) {
  console.log(watch.state, watch.task?.status)
}

For automation:

The watch stays open through review. It finishes when the task reaches done or failed and its cycle has settled, because review can reopen a task.
A cycle that ends first ends the watch too. If the task’s cycle is canceled, fails, or finishes without it, the watch ends with state: "unmet" and a reason such as Task cycle was canceled.
A watch has no time limit. It stays open as long as the task runs. If the connection drops, start a new one; the first thing it receives is the task’s current status.

Listing tasks

hlix tasks list

Inside a folder bound to a project, this lists that project’s tasks; anywhere else it lists the whole workspace. Expected result:

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

--project <id> (string, default the bound project): restrict to one project.
--status <status> (string): restrict to one of the statuses above.

hlix tasks list --status failed --json

With no matches it prints No tasks. and exits 0.

Reading one task

hlix tasks get "$TASK_ID"

Expected result:

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

Use hlix tasks get --json for the full API response.

Task conversation

GET and POST /v1/api/tasks/:id/comments are the task’s conversation — messages between you and the agents working it. Use review comments for feedback anchored to a commit and file.

curl -sS -X POST "$HLIX_BASE_URL/v1/api/tasks/$TASK_ID/comments" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"body":"Use the existing logger rather than console."}'

body is required (1–10 000 characters). An optional messageId (uuid) makes the post idempotent: replaying the same id with the same body returns the stored message instead of duplicating it. A view-only portal client may comment.

Common questions

Can I cancel a running task? Stop its cycle with POST /v1/api/cycles/:id/stop. This cancels the cycle and stops automatic retries.

Why did hlix tasks watch end with an error line? The task’s cycle ended before the task did — canceled, failed, or finished without it. The line says which. A canceled cycle does not run again on its own; a failed one runs again on the same checklist and branch, and the project manager may re-plan the open work.

Where are the logs? Follow the build agent’s progress live on the cycle in the dashboard. tasks watch follows the task’s status, not its output.

If a task will not run

Task stays queued — check its cycle’s dependencies, the build agents available and delivery status. Add new delivery work through the cycle endpoint shown above.
Task stays blocked — a task it depends on has not finished, or an agent is waiting for your answer. See Approvals.
{"error":"Task not found"} as a stream frame — the id is wrong, or it belongs to another workspace. Check X-Organization-Id.
{"error":"This action is restricted to the agency"} — you are signed in as a portal client. Clients read and comment; they do not create tasks.
The watch ends while the task still runs — the connection dropped. Start a new watch; it begins with the current status.