Quickstart: ship your first task

Import a project, start a run, watch an agent build, and read the verified diff it produced.

Import a local project, give the project manager a brief, and inspect the resulting code change and review evidence.

Prerequisites

The hlix CLI installed and authenticated
A workspace ID and an API key from Developer tools → API keys
Git, and a project directory you are authorized to upload
Model access configured: Hlix-managed funding, a provider API key, or a supported connected subscription

Export the two values once; every API step below reuses them.

export HLIX_API_KEY='…'
export HLIX_WORKSPACE_ID='<workspace-id>'
export HLIX_BASE_URL='https://server.hlix.ai'

The five steps

Import the project. Start with a dry run so you see exactly what leaves your machine.

cd path/to/project
hlix import . --dry-run
hlix import .

Expected result:

Imported into HLIX Repos: acme-invoices (9f2c1b0)

hlix status prints the new project ID — copy it, the next step needs it. If the dry run reports blockers, resolve them before continuing; Move an existing project to hlix lists each blocker and its fix.

export PROJECT_ID='6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41'

hlix status confirms the binding, and is the command to reach for whenever you are unsure which workspace a folder points at:

folder      /Users/you/acme-invoices
workspace   org_2p9xk4 (from project)
api         https://server.hlix.ai (from project)
credential  environment (HLIX_API_KEY)
project     6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
HLIX Repos  9f2c1b0ae4d5768a3c2f1e0d9b8a7c6d5e4f3a2b
local       412 files, matches the last sync
cloud       commit 9f2c1b0ae4d5768a3c2f1e0d9b8a7c6d5e4f3a2b, up to date

Start the run with a brief. Describe the result you want and how to check it. The project manager turns the brief into cycles and tasks.
- Dashboard
- API
In the dashboard: open app.hlix.ai, pick the imported project, and describe the outcome in the composer. It calls the same endpoint as the API path.
Over the API:
Terminal window
curl -sS -X POST "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/start" \ -H "x-api-key: $HLIX_API_KEY" \ -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \ -H 'content-type: application/json' \ -d '{"brief":"Add a health endpoint at GET /healthz that returns 200 with the build SHA, and cover it with a test."}'
Expected result:
{"started":true}
started: true means the project manager has started. Follow progress in the dashboard. If the project uses an initial proposal, an agency member must approve its ready scope before the first build agent starts; see Approvals.
Find the task the project manager created. Tasks appear as the project manager prepares the cycle.
Terminal window
```
hlix tasks list
```
Run from inside the imported folder, this needs no arguments — it defaults to the project this folder is bound to. Expected result:
```
ID                                    STATUS    TITLE
------------------------------------  --------  ------------------
b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90  queued    Add GET /healthz
```
No tasks. means planning has not produced any yet. Follow planning in the dashboard, then run the command again.
Terminal window
```
export TASK_ID='b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90'
```
Watch the agent work. hlix tasks watch follows the task’s live status and exits when the task is over.
Terminal window
```
hlix tasks watch "$TASK_ID"
```
Expected result — one line per status change, ending at a terminal status:
```
queued
building
done
```
Add --json to get one envelope per line (JSONL) instead, which is what automation should read.
Read what it delivered. Open the change and inspect its verification and review results. Reviewed cycles collect on the preview branch, and the project’s review shows the pull request and check outcomes, including skipped checks.
Terminal window
```
curl -sS "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/review" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"
```
Expected result, abridged:
```
{
  "canMerge": true,
  "pullRequests": [
    { "repoName": "acme/shop", "url": "https://github.com/acme/shop/pull/42", "headSha": "9f2c1b0ae4d5768a3c2f1e0d9b8a7c6d5e4f3a2b", "baseBranch": "main" }
  ],
  "verifiedCycles": 1,
  "passedJourneys": 1,
  "totalJourneys": 1
}
```
The pull request holds every reviewed cycle. The final merge requires your approval. Reviewing output explains what review checked and how a rejection goes back onto the checklist.

What just happened

hlix import .              your folder ──▶ a cloud Project
POST /projects/:id/start   your brief  ──▶ the project manager

   Project manager
     │  plans a roadmap
     ▼
   Cycle
     │  hires one build agent, plans a checklist of tasks
     ▼
   Build agent run ── one Cloud Machine, the cycle's own branch
     │  works the checklist in order, commits, pushes
     ▼
   Review ──▶ the review evidence you just read

The project manager planned a cycle, a build agent worked its checklist on a separate branch, and a review agent checked the result. Each run used a fresh Cloud Machine from the project’s Project Environment, deleted when the run ended.

If a step fails

No credential. Run `hlix auth login`, or set HLIX_API_KEY for CI. — the CLI has no stored login. See Authenticate.
This folder is already bound to a project. Use hlix push or sync. — the folder was imported before. Use hlix push to sync the updated files instead of importing again.
Import requires approval. Review --dry-run, then use --yes. — a non-interactive import never approves an upload on your behalf.
workspace_mismatch from any hlix command — a --workspace, --base-url, or HLIX_* value contradicts the folder’s binding. Drop the override; hlix status shows which source decided what.
{"error":"Project run already in progress","status":"running"} — a run is already active. Follow its progress in the dashboard.
{"error":"Project not found"} on start — the project ID is wrong, or belongs to another workspace. Check X-Organization-Id.
{"error":"No active organization"} — the X-Organization-Id header is missing and the API key resolved no default tenant.
An empty task list that stays empty — read the project’s activity in the dashboard. A run that failed during planning reports there, not on the task list.

Quickstart: ship your first task

Prerequisites

The five steps

What just happened

If a step fails

Next steps