Executing Workflows

Once you build a workflow, you need to run it.

Note: The SDK builds workflow definitions; the Culvii platform runs them. You author a workflow with @culvii/kit, deploy it with the culvii CLI, and the platform handles runtime execution, pausing, and state management.

Inspecting the definition

The SDK provides methods to convert your workflow into the JSON format the platform expects. These are useful for testing and debugging the shape you're about to deploy.

// Get the raw serialized definition
const definition = workflow.toJSON();

// Or get the validated runtime shape (throws if a connection points
// at a step that isn't in the workflow)
const runtimeShape = workflow.toRuntimeWorkflow();

Deploying your workflow

You don't serialize and upload the workflow by hand. Instead, export your Workflow from a file the CLI can discover — a .culvii.ts file, or a file listed under entrypoints: in culvii.yaml — and deploy it:

culvii deploy --env sandbox --workspace my-workspace

The CLI evaluates your entrypoints, collects every Workflow you construct, validates the definitions, and sends them to the platform. Use culvii dev for local iteration against your dev environment. The platform takes over execution from there.

Pausing and resuming

Workflows often need to wait for external events, like a user clicking an email link or an admin approving a request.

When a step is configured to wait, the platform pauses the workflow execution, serializes the current state, and stores it. Once the external event occurs (via a webhook or API call), the platform rehydrates the state and resumes execution from the exact point it paused.

You don't need to write custom state management code for this. The platform handles the serialization and resumption automatically.

State and data flow

As a workflow executes, each step receives input data, processes it, and passes output data to the next connected step.

The platform maintains this state throughout the execution lifecycle. If a workflow fails or pauses, you can inspect the state of each step in the Culvii dashboard to debug data issues or trace execution paths.