Workflows
A workflow has two sides, and they use different commands:
- The spec — a
WorkflowSpec v1JSON document describing stages, nodes, and edges. Managed withworkflow push. - The runs — traces produced while a workflow executes. Sent with
workflow push-runandworkflow watch-run.
Pushing a spec
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:
- 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.
- Graph rules a schema cannot express — type compatibility across edges, fan-in legality, switch case coverage, and acyclicity.
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
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.
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.
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.