Command

Sovereign

Sovereign tier required. 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

- 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

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.

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 for ref-safe repository operations, or use Valdr Tools for the Valdr MCP action surface.

GitHub Session Steps