Working Directory (dir:)

By default every shell command runs in the workflow directory — the folder containing the orchstep.yml being run. The dir: field changes that for a workflow, a task, or a single step.

# this orchstep.yml lives in ~/myrepo/
tasks:
  test:
    dir: backend                 # every step in this task runs in ~/myrepo/backend
    steps:
      - name: deps
        func: shell
        do: go mod download      # ~/myrepo/backend
      - name: api-tests
        func: shell
        dir: backend/api         # this step overrides the task -> ~/myrepo/backend/api
        do: go test ./...

Precedence

Most specific wins:

step dir:  >  task dir:  >  workflow dir:  >  the workflow directory (default)

A step's dir: replaces the task's dir: (it does not nest under it).

Path rules

• Relative paths resolve against the workflow file's directory, not your current shell directory — so a workflow behaves the same no matter where you run it from.
• Absolute paths (/opt/app) are used as-is.
• ~ and ~/path expand to your home directory.
• Values are template-resolved, so dir: "{{ vars.service }}" works.

Errors

If the resolved directory doesn't exist, the step fails fast with the resolved path so you can see exactly where it looked:

task 'test', step 'api-tests': working directory 'backend/api' not found (resolved to /…/backend/api)
  Check the dir: value — relative paths resolve against the workflow file's directory.

dir: applies to shell steps. It has no effect on non-command functions like http, assert, or transform.

See also

Working Directories — a full guide with monorepo and umbrella examples, and how to run a workflow from a different directory than its orchstep.yml.