> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# workflows runs test

> Start a test run of a workflow.

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`](/cli/reference/workflows-runs-get) to fetch status and progress, or [`clay workflows runs steps`](/cli/reference/workflows-runs-steps) for per-step execution detail.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay workflows runs test <workflowId> [--input <json|file|->]
```

## Arguments

| Argument     | Description                              |
| ------------ | ---------------------------------------- |
| `workflowId` | Workflow id, e.g. `wf_abc123`. Required. |

## Flags

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

## Output

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
}
```

| Field                | Type           | Description                                                                     |
| -------------------- | -------------- | ------------------------------------------------------------------------------- |
| `runId`              | string         | Run id. Pass to [`clay workflows runs get`](/cli/reference/workflows-runs-get). |
| `workflowId`         | string         | Workflow the run belongs to.                                                    |
| `workflowName`       | string \| null | Workflow display name, or `null`.                                               |
| `status`             | string         | Run status at start. See the status values below.                               |
| `createdAt`          | string         | When the run was created.                                                       |
| `updatedAt`          | string         | When the run was last updated.                                                  |
| `workflowSnapshotId` | string         | Snapshot version the run executes.                                              |
| `batchId`            | string         | Present when the run is part of a batch.                                        |
| `triggerId`          | string         | Present 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

| Code               | Exit | Notes                                                          |
| ------------------ | ---- | -------------------------------------------------------------- |
| `validation_error` | 2    | `--input` is unreadable, not valid JSON, or not a JSON object. |
| `not_found`        | 6    | No workflow with that id.                                      |
| `auth_forbidden`   | 3    | The API key lacks the `terracotta:cli` scope.                  |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```