Output & Exit Codes

orchstep run renders its progress in one of three modes, chosen with --output (it also auto-detects: a real terminal gets pretty, a pipe or CI gets plain).

orchstep run deploy                 # pretty on a terminal, plain when piped
orchstep run deploy --output plain  # force plain
orchstep run deploy --output json   # structured result

Plain

Workflow: deploy
Task: main
  Step: build
  $ make build
...build output...
  [ok] build
Result: success

JSON

--output json prints exactly one JSON document (nothing else on stdout), so you can pipe it straight into jq:

{
  "workflow": "deploy",
  "task": "main",
  "status": "success",
  "steps": [
    { "task": "main", "name": "build", "status": "ok", "output": "..." }
  ]
}

orchstep run deploy --output json | jq -r '.status'
orchstep run deploy --output json | jq '.steps[] | select(.status=="failed")'

Logs and structured output: --json-file

--output json is exclusive - it suppresses the logs so stdout is pure JSON. When you want both the human-readable logs and a machine-readable result (the common CI case), keep a normal output mode and write the structured result to a file:

orchstep run deploy --output plain --json-file result.json
# stdout: the full plain logs (visible in the CI run)
# result.json: the same RunResult document, for a later step / artifact

--json-file works with any --output mode (pretty, plain, or json) and is written even when the run fails, so a downstream step can always inspect what happened.

Exit codes

orchstep run follows a documented exit-code contract, so CI can branch on the kind of failure, not just pass/fail:

orchstep run check
case $? in
  0) echo "ok" ;;
  4) echo "an assertion failed" ;;
  3) echo "the workflow itself is broken" ;;
  *) echo "a step failed" ;;
esac

This pairs with the engine-version (required.orchstep) and lockfile checks: those surface as exit 3 (load) so a misconfigured pipeline fails fast and distinctly from a genuine task failure.