When your bash scripts outgrow bash (but you don't want a platform)

Every team has the script. It started as five lines that built and deployed a service. Two years later it's 300 lines of bash with set -euo pipefail, a dozen if [ -z "$VAR" ] guards, retry loops someone copy-pasted from Stack Overflow, and a comment that just says # don't touch this.

You've outgrown bash. But you don't want to stand up Argo, or wire your runbook into Jenkins, or learn a YAML-of-YAML DSL just to run a few ordered shell commands with variables and error handling.

That gap — between a script and a platform — is where OrchStep lives.

What it actually is

OrchStep is a YAML-first workflow orchestration engine that ships as a single binary. No server, no control plane, no signup. You describe a workflow in orchstep.yml and run it from the terminal (or inside the CI you already have).

A few principles worth knowing up front, because they shape everything:

• No platform required. It's a CLI binary, not a SaaS. It runs inside your existing CI/CD instead of replacing it.
• Shell-first. OrchStep doesn't reimplement terraform, kubectl, aws, or docker — it delegates to them. Your steps are the commands you already run; OrchStep gives them structure.
• Built for the terminal. Keyboard-driven, scriptable, --format json on every command.

It's honestly not for everyone: if make covers you, use make; if you genuinely need a scheduler, a queue, and multi-tenant RBAC, you need a platform. OrchStep is for the large middle — "I've outgrown bash but a platform is overkill."

Two minutes to your first workflow

Install it however you like:

curl -fsSL https://orchstep.dev/install.sh | sh
# or: brew install orchstep/tap/orchstep
# or: npm i -g orchstep   /   pip install orchstep

Then scaffold a starter — it writes a complete, runnable file, not a stub:

orchstep init

The whole shape of a workflow is small enough to read in one breath:

name: hello
tasks:
  greet:
    steps:
      - name: say-hello
        func: shell
        do: echo "Hello from OrchStep!"

Run it:

orchstep run greet

The generated file lints clean and runs green immediately — no fiddling:

The part that makes it feel like a tool, not a config file

Don't remember the task name? Press a key, not your memory:

orchstep menu

You get a keyboard-driven picker with single-keystroke hotkeys and fuzzy search — and, importantly, it refuses to hang in a pipeline (run it in CI and it exits cleanly instead of waiting for a TTY).

What you get over a shell script

The same commands you already run, but now with structure that used to be your problem:

• Ordered steps with named outputs you can reference downstream
• Variables with real scoping instead of a wall of exports
• Conditionals and loops that read like intent, not case/while gymnastics
• Retries, timeouts, and try/catch/finally as syntax, not hand-rolled
• Environments so one workflow targets dev/staging/prod without copy-paste
• A dry-run that shows you the resolved plan before anything executes

We'll dig into each of those across this series. None of it requires giving up the shell — it just stops you from rebuilding the same plumbing in every script.

Where this series is going

This is part 1 of a hands-on developer series. Next up:

1. Workflows that read like intent — tasks, steps, functions, variables, and outputs
2. One workflow, every environment — env groups, dotenv, and a coverage matrix that catches missing vars before you deploy
3. See what will happen before it does — dry-run, lint, and the optional local dashboard
4. Capture an agent's work, replay it for free — using OrchStep with AI agents

If you want to skim ahead, the Introduction and Quick Start cover the basics, and there's a 90-second tour of the CLI if you'd rather watch than read.

Got a gnarly bash script you'd retire if this looked good? Drop it in the comments — I'll show what it looks like as an OrchStep workflow.