Skip to main content
Start a test run of a workflow. The command returns immediately with a run id — it does not poll or wait. Use clay workflows runs get to fetch status and progress, or clay workflows runs steps for per-step execution detail. 
clay workflows runs test <workflowId> [--input <json|file|->]

​
Arguments

ArgumentDescription
workflowIdWorkflow id, e.g. wf_abc123. Required.

​
Flags

FlagDescription
--input <json|file|->Workflow input as a JSON object: inline JSON, a file path, or - to read from stdin. Defaults to {}.

​
Output

{
  "runId": "wfr_xyz789",
  "workflowId": "wf_abc123",
  "workflowName": "Lead enrichment",
  "status": "pending",
  "createdAt": "2026-06-01T00:00:00Z",
  "updatedAt": "2026-06-01T00:00:00Z",
  "workflowSnapshotId": "wfs_123",
  "batchId": "batch_123",
  "triggerId": "trg_123"
}
FieldTypeDescription
runIdstringRun id. Pass to clay workflows runs get.
workflowIdstringWorkflow the run belongs to.
workflowNamestring | nullWorkflow display name, or null.
statusstringRun status at start. See the status values below.
createdAtstringWhen the run was created.
updatedAtstringWhen the run was last updated.
workflowSnapshotIdstringSnapshot version the run executes.
batchIdstringPresent when the run is part of a batch.
triggerIdstringPresent when the run was started by a trigger.
Run status is one of: pending (queued but not yet started), running (actively executing nodes), waiting (blocked on an async operation or concurrency slot), paused (paused by an operator — resume to continue), completed (finished successfully), or failed (terminated with an error).

​
Errors

CodeExitNotes
validation_error2--input is unreadable, not valid JSON, or not a JSON object.
not_found6No workflow with that id.
auth_forbidden3The API key lacks the terracotta:cli scope.

​
Examples

clay workflows runs test wf_abc123 | jq -r '.runId'
clay workflows runs test wf_abc123 --input '{"domain":"clay.com"}'
echo '{"domain":"clay.com"}' | clay workflows runs test wf_abc123 --input -
clay workflows runs test wf_abc123 --input inputs.json