Migrating to OrchStep

Coming from Make, Just, Task, npm scripts, or a scripts/ folder? Your commands map onto OrchStep with almost no change in muscle memory.

Nobody adopts a task runner greenfield. You already have a Makefile, a justfile, a Taskfile.yml, a pile of npm run scripts, or a scripts/ folder - and it mostly works. The good news: whatever you run today maps onto OrchStep cleanly, and the muscle memory barely changes.

make build            ->   orchstep run build
just deploy prod      ->   orchstep run deploy --var environment=prod
task test             ->   orchstep run test
npm run lint          ->   orchstep run lint
./scripts/release.sh  ->   orchstep run release

The universal map

Every tool has the same handful of concepts. Here is how they land in OrchStep:

You want to...	Make	Just / Task / npm / shell	OrchStep
Run a command	`make build`	`just build` / `task build` / `npm run build`	`orchstep run build`
List commands	(none)	`just --list` / `task --list`	`orchstep list-tasks`
One command, no args	`make`	`just`	`orchstep run` (the `main` task)
Pass a value	`make build V=2`	`just build 2`	`orchstep run build --var v=2`
Depend on another	prerequisites	`deps:` / `&&`	a step with `task:`
Run things in parallel	`make -j`	`deps:`	a `parallel:` block
One command (no file target)	a `.PHONY` target	a recipe	a task

The full reference for the right-hand column is the CLI Reference.

Why move at all

If your current runner works, why switch? Because OrchStep adds the things a Makefile or scripts/ folder can't give you, without losing the simplicity:

ONE BINARY, RUNS ANYWHERE

No make on Windows, no Bash-isms that break on macOS vs Linux. One static binary runs the same workflow locally, in CI, and in a container.

PREVIEW BEFORE YOU RUN

orchstep run --dry-run shows every command, branch, and task call - and a visual plan - without executing anything. No more reading a Makefile to guess.

REAL DATA BETWEEN STEPS

Steps capture typed outputs (steps.build.image_tag) instead of echoing strings and re-parsing them. Conditions, retries, and assertions are built in.

REUSE ACROSS REPOS

Promote shared tasks into versioned modules - the thing a copy-pasted scripts/ folder never let you do.

You can migrate incrementally

You do not have to convert everything at once. An OrchStep step is just a shell command, so during the transition a task can call your existing tooling:

tasks:
  build:
    steps:
      - name: legacy
        func: shell
        do: make build          # call the old Makefile target while you migrate

Move one target at a time, and delete the old file when the last one is gone.

Pick your starting point

FROM MAKE

Makefile -> OrchStep - targets, prerequisites, $(VARS), .PHONY, and make -j.

FROM JUST

justfile -> OrchStep - recipes, parameters, and {{ }} interpolation (which you already know).

FROM TASK

Taskfile.yml -> OrchStep - the closest cousin: both YAML, both Go templates.

FROM NPM SCRIPTS

package.json -> OrchStep - scripts, pre/post hooks, and && chains.

FROM SHELL SCRIPTS

scripts/ folder -> OrchStep - one script per task, positional args to named variables.

< Previewing with Dry Run From Make >