DreamLake

Task operation examples

Verify the installed CLI version and target service before use. Replace the example paths, IDs, revisions and timestamps with values from your own tasks.

Set scope once per session

Task commands accept session defaults starting in CLI 0.19.1:

shell
export DREAMLAKE_NAMESPACE=ge
export DREAMLAKE_PROJECT=my-project

dl tasks list
dl 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. If the project is missing, the command fails before making an API request.

shell
dl tasks list --namespace another-team --project another-project

These defaults apply to dl 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 Memo content.

shell
dl tasks add vault --kind workstream --title 'Vault' --blurb 'Credential management'
dl tasks add vault/entries --kind stage --title 'Entries' --blurb 'Entry lifecycle'
dl tasks add vault/entries/write-recovery --title 'Write recovery' --blurb 'Safely retry writes' --to-json
dl 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

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

The UI opens the selected task/folder in an outline and waterfall. Its detail panel shows memo 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.

shell
dl tasks rename vault/entries/write-recovery --title 'Recover interrupted writes' --if-match REV_BEFORE_RENAME
dl tasks move vault/entries/write-recovery vault/entries/recovery --if-match REV_BEFORE_MOVE
dl 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.

shell
dl tasks start vault/entries/write-recovery --at '2026-09-13T20:00:00Z' --event-id recovery-start-001 --if-match REV_BEFORE_START
dl 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
dl 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
dl tasks end vault/entries/write-recovery --at '2026-09-13T20:26:00Z' --event-id recovery-end-001 --if-match REV_BEFORE_END
dl 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.

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

shell
dl 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
dl 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 memo items: prompt, comments and details

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

shell
dl tasks notes add vault/entries/write-recovery --role agent_prompt --note-id MEMO_ID_PROMPT --section recovery-agent
dl tasks notes add vault/entries/write-recovery --role comment --note-id MEMO_ID_DISCUSSION --section review-feedback
dl tasks notes add vault/entries/write-recovery --role details --note-id MEMO_ID_DESIGN
dl tasks notes list vault/entries/write-recovery --to-json

The detail panel groups links by role and opens the linked memo item. Comments use Memos 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 Memos 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 Memo content. Under the proposed first-version rule, deletion with live children fails. These are independent examples, not one mandatory sequence.

shell
dl tasks delete vault/entries/write-recovery --if-match REV_BEFORE_DELETE
dl tasks list vault --include-deleted --to-json
dl tasks restore TASK_ID_RECOVERY --if-match REV_BEFORE_RESTORE
dl 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.

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