Command

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.

Use User Tools when the same program should expose reusable typed actions and travel in a pack with an exact revision and content hash. User tools use the same host execution model and can select a working directory per step.

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
    env:
      CI: "true"
  outputs:
    ok: "$.normalized.ok"
    exitCode: "$.normalized.exitCode"
    stdout: "$.normalized.stdout"

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.

Environment overrides go under inputs.env. Names use letters, digits, and underscores and cannot start with a digit; values must be strings without NUL characters. Quote YAML booleans and numbers when using them as environment values. Commands inherit a filtered host environment, and inputs.env overrides inherited values. Set NODE_ENV explicitly when the command needs it. Anyone who can read the saved definition can read these values, so inherit credentials from the host instead of putting secrets in YAML.

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

Command steps are available on macOS and Linux. Redaction of saved command output is best effort and may miss sensitive values. You are responsible for what your command prints; keep credentials out of its output and review logs before sharing them.

Retry with a corrected command

To correct an eligible Command step before choosing Retry step, save the updated command, cwd, timeoutSeconds, or env values in the active definition under the same workflow key and version. The retry can use those settings; the run’s steps, dependencies, output mappings, and sourceSessionUlid stay unchanged. This lets you repair a bad command without changing the rest of the in-progress workflow.

If those settings changed, the UI opens Retry with saved Command changes? and lists the changed fields. Environment changes list variable names, not values. Review the saved definition before choosing Retry with saved changes. If it changes again, refresh and review the newer settings. MCP callers can use the retry preview’s expectedContentHash for the same stale-review check; see Retry a step.

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

Continue with User Tools when a command should become a reusable, typed action. For other step kinds, return to Workflow Steps.