From Just

If you use just as a command runner - a justfile full of recipes like build, test, deploy - OrchStep is a direct, friendlier replacement. You keep the same mental model (named commands that run shell, with variables and dependencies) and gain typed outputs, parallel blocks, and shareable modules.

The 30-second version

just                          ->   orchstep run            # default task
just build                    ->   orchstep run build
just deploy production 2.1.0  ->   orchstep run deploy --var environment=production --var version=2.1.0
just --list                   ->   orchstep list-tasks

How the concepts map

Side by side

version := "1.0.0"
environment := "staging"

build:
    echo "building v{{version}}"

test:
    echo "running tests"

deploy env=environment ver=version:
    echo "deploying v{{ver}} to {{env}}"

ci: test build

name: app
desc: Build, test, and deploy the app

defaults:
  version: "1.0.0"
  environment: "staging"

tasks:
  build:
    steps:
      - name: compile
        func: shell
        do: echo "building v{{ vars.version }}"
  test:
    steps:
      - name: unit
        func: shell
        do: echo "running tests"
  deploy:
    steps:
      - name: ship
        func: shell
        do: echo "deploying v{{ vars.version }} to {{ vars.environment }}"
  ci:                         # recipe deps become task calls
    steps:
      - name: run_test
        task: test
      - name: run_build
        task: build

Run it

orchstep run build
orchstep run deploy --var environment=production --var version=2.1.0

$ orchstep run deploy --var environment=production --var version=2.1.0
  $ echo "deploying v2.1.0 to production"
deploying v2.1.0 to production
Result: success

Just's positional recipe arguments (just deploy production 2.1.0) become the explicit, order-free named --var environment=production --var version=2.1.0. List everything with orchstep list-tasks.

Gotchas worth knowing

• {{x}} becomes {{ vars.x }}. Same braces you already know - just add the vars. prefix so OrchStep knows where to look the value up.
• Positional to named. Just parameters are positional at the call site; OrchStep uses order-free named --var, so you never have to remember which argument came first.
• [private] becomes a leading underscore. A [private] recipe maps to a task named with a leading _ - it stays callable internally but is kept out of orchstep list-tasks and the menu.
• env is reserved. Don't name a variable env - that namespace is for environment variables ({{ env.PATH }}). Use environment (the loader will stop you with a clear error otherwise).

What you gain

• orchstep run --dry-run previews the whole chain (including ci -> test/build).
• The same file runs on Windows without just installed.
• Steps pass typed outputs instead of echoing strings.
• Shared recipes can become versioned modules.

Where to go next

• Composing Tasks - how task: calls pass parameters.
• Variables and Outputs - the {{ vars.x }} namespace in depth.
• CLI Reference - every flag for orchstep run.