CLI
Workflows (v3)
Workflow v3 templates describe an automation as a node graph — triggers wired to steps — stored as JSON. This page walks the dev loop: scaffold a template, validate it, test it against a development runner, then deploy it to production with a hot-swap so live traffic isn't interrupted.
For CI/CD pipeline automation, see CI/CD Integration.
Before you start. Workflow commands talk to the dcupl cloud, so they need project credentials — configure them once with dcupl config set (see Cloud Sync). A runner is the managed environment in the cloud that executes a deployed workflow; each project has one or more (typically a dev runner for testing and a prod runner for live traffic). You deploy and test against a runner — list them with dcupl workflow runners list.
Runtime budgets are hard limits, enforced at execution time: 10s total per workflow, 5s per request node, and 500ms per script node. A node that exceeds its budget is terminated.
The dev loop
You edit a *.workflow-v3.json file locally, exercise it against a runner, and deploy it with a hot-swap.
scaffold from the example shape — no guessing: dcupl schemas get TemplateV3 --example > my.workflow-v3.json
the agent / you edit my.workflow-v3.json, then validate: dcupl workflow validate --file my.workflow-v3.json --local-only — output: ✓ Template valid — 2 triggers, 4 nodes
find an available dev runner: dcupl workflow runners list — output: [ { "uid": "run_dev_2c", "key": "dev", "type": "development" }, { "uid": "run_prd_9a", "key": "prod", "type": "production" } ]
test on the dev runner with a sample input: dcupl workflow test --file my.workflow-v3.json --runner run_dev_2c \ --input '{"orderId":"123"}' --wait — output: { "status": "success", "durationMs": 612, "nodes": 4 }
deploy to prod — waits for the hot-swap: dcupl workflow deploy --file my.workflow-v3.json --runner run_prd_9a --yes — output: ✓ Deployed → run_prd_9a (hot-swapped in 1.2s)
1 · Scaffold & edit
Start from the example shape rather than a blank file, then wire up triggers and steps within the runtime budgets above. See Schemas for more on schemas get.
2 · Validate
Validate locally or against a runner's environment.
3 · Find your runners
List them to tell dev and prod apart.
4 · Test on a dev runner
This deploys the template to the runner, then exercises it.
--node <id> | Exercise a single node |
--input <json> | Input payload |
--state <json> | Seed workflow state |
--trigger-key <str> | Fire a specific trigger |
--wait | Wait for the run to finish and return its result |
5 · Deploy to a prod runner
Deploy waits for the hot-swap to complete by default. Remove a deployed workflow with dcupl workflow undeploy --id <uid> --yes.
| Flag | Default | Purpose |
|---|---|---|
--yes | — | Skip the confirmation prompt |
--wait | true | Wait for the hot-swap before returning |
--no-wait | — | Return immediately, don't wait for the swap |
--swap-timeout <ms> | 30000 | How long to wait for the swap |
Inspecting workflows
Once a workflow is deployed, these commands help you check its state and debug runs. To debug a failed run, find it in the history, then trace it node by node.
| Command | What it shows |
|---|---|
dcupl workflow list | All workflows |
dcupl workflow get --id <uid> | A workflow's details |
dcupl workflow template --id <uid> | Deployed template — drift check vs. the runner |
dcupl workflow status --id <uid> | Live status |
dcupl workflow history --id <uid> | Past runs (runId, status, duration) |
dcupl workflow trace --id <uid> --run <runId> | Node-by-node state for a run |
workflow template is useful for catching drift — if the template on the runner no longer matches your local file, redeploy.