DreamLake

Workflows

A workflow has two sides, and they use different commands:

  • The spec — a WorkflowSpec v1 JSON document describing stages, nodes, and edges. Managed with workflow push.
  • The runs — traces produced while a workflow executes. Sent with workflow push-run and workflow watch-run.

Pushing a spec

terminalbash
dl workflow push ./pipeline.workflow.json

The .workflow.json (or .json) suffix is optional, so dl workflow push ./pipeline finds the same file.

The workflow name comes from the spec's own name field. --name overrides it, which is how you push one spec under two names.

Every push appends a new version. The command prints the version it wrote.

Validation

The spec is validated locally, before anything is uploaded. An invalid spec costs you nothing but the error message.

Two layers run:

  1. The JSON Schema — required fields, types, and the shape of each node family. This is the same schema the Python CLI and the server use, so all three accept and reject exactly the same specs.
  2. Graph rules a schema cannot express — type compatibility across edges, fan-in legality, switch case coverage, and acyclicity.
output
spec failed validation (3 problem(s)):
  - nodes/0: Instance does not have required property "title".
  - nodes/0: is not valid under any of the given schemas
  - stages/0: Instance does not have required property "title".

A failed oneOf reports one line rather than listing what each alternative wanted. A compute node is not "missing sampler" — it simply is not a sampler.

Managing workflows

terminalbash
dl workflow list
dl workflow show my-flow
dl workflow update my-flow --description "..." --tags a,b
dl workflow delete my-flow          # soft — version history survives

With a server that includes the dreamlake-workspace #1343 fix (not yet released), workflow delete also removes the workflow from every project it was filed in. There is no restore; a new workflow with the same name can then take its place.

workflow create and workflow update --file handle a separate, script-based workflow format. They are unrelated to push and do not share its versioning.

Run traces

These are for the process executing a workflow, not for day-to-day use.

terminalbash
dl workflow push-run my-flow ./wf_abc123.json
dl workflow watch-run my-flow ./wf_abc123.json --interval 5

push-run sends one snapshot. watch-run keeps sending them until the run leaves the running state, then sends a final one.

Snapshots are reduced to fit the server's body limit. When a run is large, free-text previews are capped and older log lines are dropped first; the status, the phase and agent skeleton, and the run totals always survive.

Spec content is written directly to storage

Like artifact push, workflow push brokers scoped credentials and writes the spec to object storage itself. The spec never passes through the API server.

Project ownership-transfer boundary

Project sharing and attachment support do not make a Workflow transferable. Workflow references still block the entire project move request. That workflow includes owned Memos, Artifacts and Envs with the matching client/backend; Source, Workflow, Annotation and structural content remain unsupported. Do not omit a Workflow from a mixed manifest, silently detach it, or copy/delete it to report a partial transfer as complete. No standalone Workflow transfer is added.