# Command
{{< tier level="sovereign" note="Command steps bring builds, tests, and other repository-local checks into an inspectable workflow run." >}}

Use a **Command** step when a workflow needs to run an existing build, test, validation, or other non-interactive shell command. Valdr records the outcome and captured output with the step attempt so later steps can route on the result.

## Configuration

```yaml
- key: verify_change
  name: Verify Change
  kind: tool
  needs: [implement]
  tool:
    id: command
    action: run
  inputs:
    command: npm test
    sourceSessionUlid: "${steps.implement.outputs.sessionUlid}"
    timeoutSeconds: 600
  outputs:
    ok: "$.normalized.ok"
    exitCode: "$.normalized.exitCode"
    stdout: "$.normalized.stdout"
```

| Input | Required | Purpose |
| --- | --- | --- |
| `command` | Yes | One non-interactive shell command; multiline commands and pipelines are supported |
| `cwd` | No | Absolute path, or a path resolved from the selected worktree or project repository |
| `sourceSessionUlid` | No | Existing Valdr agent session whose worktree supplies the base directory |
| `timeoutSeconds` | No | Stop after this many seconds; defaults to `300`, while `0` disables the timer |

When `cwd` is omitted or relative, Valdr resolves it from the selected session worktree, the run's creating session worktree, or the registered project repository. This selects a starting point; it is not containment. Relative paths containing `..`, symlinks, and absolute paths can resolve outside that worktree or repository.

## Results

Command results include `status`, `ok`, `exitCode`, `signal`, `stdout`, `stderr`, `durationMs`, and the resolved `cwd`. Valdr captures up to 1 MiB from each output stream and also reports the total byte counts and truncation flags.

A zero exit code produces `ok: true`. A non-zero exit, timeout, signal, or operator cancellation produces `ok: false` and follows the step's failure policy.

## Trust and side effects

{{< callout type="warning" >}}
Commands run on the workflow host with the host user's permissions and ordinary environment. They are not sandboxed. Run only workflow definitions you trust, and remember that retrying can repeat command side effects.
{{< /callout >}}

Command steps are available on macOS and Linux. Valdr redacts detected secrets before saving command output.

## Retry with a corrected command

When **Retry step** is eligible, Valdr rereads the active saved definition at the same workflow key and version. The retry can pick up corrected `command`, `cwd`, and `timeoutSeconds` values while preserving the run's frozen graph, output mappings, and `sourceSessionUlid`. This lets you repair a bad command without silently changing the rest of the in-progress workflow.

## Stop a running command

Select the active attempt in **Runs** and choose **Stop command**. Valdr cancels that exact running command attempt and preserves any partial output already captured. The workflow blocks by default, or fails when the step sets `onFailure.action: fail`. **Retry step** is available when the current or latest attempt is failed or blocked and its error category is safe to repeat; authored `retry.maxAttempts` is a reported attempt count, not a manual recovery cap or automatic retry/backoff schedule.

## Next step

Return to [Workflow Steps](../), use [Git](../git/) for ref-safe repository operations, or use [Valdr Tools](../tool/) for the Valdr MCP action surface.