culvii workflow run
Start a workflow execution.
Synopsis
culvii workflow [--env <env>] run <workflow> --trigger <node-name> [--payload <json>] [--payload-file <path>] [--mocks-file <path>] [--json]
Description
Starts a workflow execution in feedback-mode. This mode allows you to test workflows with simulated inputs and mocked outputs for external services.
- Triggering: Use
--triggerto specify the starting node. If it's a manual trigger, the--payloador--payload-fileis injected directly into it. - Mocking: The
--mocks-fileallows you to provide pre-defined outputs for specific nodes, keyed by their stepid.- Requirement: External connector nodes,
core.http, andcore.browserAutomationmust be mocked in feedback-mode. - Unmocked: Core logic nodes (like
core.if,core.set) andcore.agentcannot be mocked; they always execute their real logic.
- Requirement: External connector nodes,
- Mocks File Format: A JSON file containing either a single object (mapping node IDs to outputs), an array of such objects, or a specialized object with a
batcheskey:{ "batches": [[...]] }.
Flags
| Flag | Required | Description |
|---|---|---|
--env | - | Target environment (dev, sandbox, or prod). Defaults to active context. |
--trigger | ✓ | Trigger node name. |
--payload | - | Trigger payload as JSON. |
--payload-file | - | Read trigger payload from a JSON file. |
--mocks-file | - | JSON object mapping node IDs to mock outputs. |
--json | - | Print machine-readable JSON. |
Examples
culvii workflow run my-workflow --trigger manual-trigger --payload '{"key": "value"}'
Error behaviour
| Condition | Message | Exit |
|---|---|---|
| Both payload flags | "Use only one of --payload or --payload-file" | 1 |
| Invalid JSON | "<label> is not valid JSON: <error>" | 1 |
| Invalid mocks file | "Mocks file must contain an object keyed by workflow node ID" | 1 |
| Workflow not found | "Workflow not found: <workflow>" | 1 |