Task operation examples

Examples match the #301 implementation. Verify the installed CLI version and target service before use. Paths, IDs, revisions and timestamps are illustrative; use observed values.

Set scope once per session

Task commands accept session defaults starting in CLI 0.19.1:

export DREAMLAKE_NAMESPACE=ge
export DREAMLAKE_PROJECT=my-project

dreamlake tasks list
dreamlake tasks show vault/entries/write-recovery

For each argument, an explicit flag overrides its environment variable. Namespace falls back to the authenticated user's namespace when neither is set. Project must be supplied by --project or DREAMLAKE_PROJECT; an empty environment value counts as unset. Existing namespace/project syntax and order are unchanged:

dreamlake tasks list --namespace another-team --project another-project

These defaults apply to dreamlake tasks commands only. No context file or global selected project is written. Agent runners should inject the variables into every tool process, including resumed sessions; an export in one isolated shell may not carry into the next. Give each session its own environment. Use existing --remote / DREAMLAKE_REMOTE settings to select the server.

The examples below use these session defaults. --kind defaults to task. Mutations read the current revision unless --if-match is supplied; timed events default to now and generate an event ID. Keep explicit revisions and event IDs when recording a known observation or retrying an uncertain write.

Create folder-like tasks and subtasks

Parents must already exist; add does not implicitly create missing ancestors. These tasks need no Note content.

dreamlake tasks add vault --kind workstream --title 'Vault' --blurb 'Credential management'
dreamlake tasks add vault/entries --kind stage --title 'Entries' --blurb 'Entry lifecycle'
dreamlake tasks add vault/entries/write-recovery --title 'Write recovery' --blurb 'Safely retry writes' --to-json
dreamlake tasks list vault --tree --to-json

The create response returns stable IDs and revisions. Persist those IDs for API/evidence links; readable paths are for lookup. Use the returned current revision for edits.

Read status and show the waterfall

dreamlake tasks status vault --recursive --to-json
dreamlake tasks show vault/entries/write-recovery --to-json

The UI opens the selected task/folder in an outline and waterfall. Its detail panel shows note links and event history. A task with a start and no end has a striped open bar to the present; it does not acquire an endedAt timestamp.

Rename, move and reorder

Rename changes the title, keeping slug/path and ID. Move changes placement or slug explicitly, keeping ID. --if-match supplies the current revision; tokens below stand for successive revisions read after each operation.

dreamlake tasks rename vault/entries/write-recovery --title 'Recover interrupted writes' --if-match REV_BEFORE_RENAME
dreamlake tasks move vault/entries/write-recovery vault/entries/recovery --if-match REV_BEFORE_MOVE
dreamlake tasks reorder vault/entries --children 'TASK_ID_RECOVERY,TASK_ID_READ' --if-match PARENT_REVISION

Reorder supplies the full existing child-ID array in the desired order; it does not add/remove membership. The example assumes both listed children exist. On conflict, read the current parent rather than overwriting concurrent edits.

Start, discrete progress, end and done

These lifecycle commands log the corresponding typed events. Example times describe actual task work, never PR creation/merge. The examples below address a task before any optional move above.

dreamlake tasks start vault/entries/write-recovery --at '2026-09-13T20:00:00Z' --event-id recovery-start-001 --if-match REV_BEFORE_START
dreamlake tasks progress vault/entries/write-recovery --mode discrete --completed 3 --total 5 --unit checks --at '2026-09-13T20:15:00Z' --event-id recovery-progress-003 --if-match REV_BEFORE_PROGRESS
dreamlake tasks progress vault/entries/write-recovery --mode discrete --completed 5 --total 5 --unit checks --at '2026-09-13T20:25:00Z' --event-id recovery-progress-005 --if-match REV_BEFORE_FINISH_PROGRESS
dreamlake tasks end vault/entries/write-recovery --at '2026-09-13T20:26:00Z' --event-id recovery-end-001 --if-match REV_BEFORE_END
dreamlake tasks status set vault/entries/write-recovery --status done --at '2026-09-13T20:27:00Z' --event-id recovery-done-001 --if-match REV_BEFORE_DONE

end alone does not imply done. done does not imply acceptance. If the work ends unsuccessfully, log context and leave status not_done. Reuse an event ID only when replaying precisely the same update. Each new progress snapshot gets a new ID.

Floating-point progress

Use a separate task or explicitly designed reset when changing progress mode/unit. Here vault/ingest is an existing task using continuous progress.

dreamlake tasks progress vault/ingest --mode continuous --completed 0.375 --total 1 --unit fraction --at '2026-09-13T20:15:00Z' --event-id ingest-progress-003 --if-match INGEST_REVISION

This records 0.375 / 1 fraction. Progress is an absolute snapshot: omitting total makes the total unknown, including when a previous total was known. Mode and unit stay fixed until reopen.

Log a contextual event and list events

dreamlake tasks events add vault/entries/write-recovery --type message --message 'Replay test passed; human acceptance pending.' --at '2026-09-13T20:28:00Z' --event-id recovery-message-001
dreamlake tasks events list vault/entries/write-recovery --limit 50 --to-json

A message event never changes completion/acceptance state. Events should carry evidence references rather than secrets or raw credential-bearing command lines.

Link note items: prompt, comments and details

These are references to existing Notes/sections. Linking does not create or edit Note content. Use IDs returned by existing Notes APIs and resolve section anchors against the actual document.

dreamlake tasks notes add vault/entries/write-recovery --role agent_prompt --note-id NOTE_ID_PROMPT --section recovery-agent
dreamlake tasks notes add vault/entries/write-recovery --role comment --note-id NOTE_ID_DISCUSSION --section review-feedback
dreamlake tasks notes add vault/entries/write-recovery --role details --note-id NOTE_ID_DESIGN
dreamlake tasks notes list vault/entries/write-recovery --to-json

The detail panel groups links by role and opens the linked note item. Comments use Notes content for this first proposal, not a new Comment collection. A separate comment/post API or immutable discussion timeline is not implied. Prompt revision pinning is optional and must match Notes capabilities; record what the agent actually read when execution evidence needs it.

Soft-delete, restore and deprecate

Deletion hides the record, preserves ID/events/Note links, and never deletes Note content. Under the proposed first-version rule, deletion with live children fails. These are independent examples, not one mandatory sequence.

dreamlake tasks delete vault/entries/write-recovery --if-match REV_BEFORE_DELETE
dreamlake tasks list vault --include-deleted --to-json
dreamlake tasks restore TASK_ID_RECOVERY --if-match REV_BEFORE_RESTORE
dreamlake tasks status set vault/entries/write-recovery --status deprecated --at '2026-09-13T21:00:00Z' --event-id recovery-deprecated-001 --if-match REV_BEFORE_DEPRECATE

There is no hard-delete example. Deprecation is a visible status, distinct from soft deletion.

Equivalent status and event HTTP examples

The base URL is intentionally a non-service example domain. Use the actual supported server route only after it ships. TASK_TOKEN must come from an authorized credential source; never include it in task events.

TASK_API='https://api.example.invalid'
TASK_RESOURCE="$TASK_API/namespaces/ge/projects/my-project/tasks/TASK_ID_RECOVERY"
curl --fail-with-body "$TASK_RESOURCE/status" \
  -H "Authorization: Bearer $TASK_TOKEN"

curl --fail-with-body "$TASK_RESOURCE/events" \
  -H "Authorization: Bearer $TASK_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "eventId": "recovery-progress-003",
  "type": "progress",
  "occurredAt": "2026-09-13T20:15:00Z",
  "expectedRevision": "REV_BEFORE_PROGRESS",
  "data": {"mode": "discrete", "completed": 3, "total": 5, "unit": "checks"}
}
JSON

curl --fail-with-body "$TASK_RESOURCE/events?limit=50" \
  -H "Authorization: Bearer $TASK_TOKEN"

This HTTP progress event is equivalent to the CLI progress example, not a second independent update. Replay preserves the event ID and body. Read back status to confirm the expected projection/revision; distinguish event receipt from task completion or human acceptance.