OrchStep for solo developers

When you're the only developer, "automation" usually means a Makefile you half-remember, three shell aliases, and a notes.md with the commands you run before a release. It works because there is exactly one person who needs to understand it: you. The problem shows up two weeks later, when you come back to the project and that one person has forgotten everything.

Solo work doesn't need a platform, a build server, or a CI vendor. It needs the commands you already run, written down in an order you can re-run without thinking. That's the entire job OrchStep does at this stage — one binary, one orchstep.yml, no daemon and no account.

What automation looks like solo

At this size the pain isn't scale, it's recall. You're not running 400 jobs an hour; you're trying to remember whether the publish step comes before or after the tag, and which env var the build needed. The win is turning that tribal knowledge (where the tribe is one person) into a file you can read.

So the bar is low and honest: if a Makefile already does this for you, keep the Makefile. OrchStep earns its place the moment you want named inputs, a retry that isn't a copy-pasted until loop, or the ability to call one task from another without duplicating commands.

Two workflows worth writing down

A solo project really only needs two tasks: the inner loop you run constantly (check), and the release dance you run rarely and always second-guess (ship). Here's the whole thing.

name: sidequest
defaults:
  version: "0.1.0"
  target: staging
tasks:
  # `orchstep run check` — the inner loop
  check:
    steps:
      - name: format
        func: shell
        do: echo "formatting source"
      - name: test
        func: shell
        do: echo "running unit tests"
      - name: build
        func: shell
        do: echo "building binary"

  # `orchstep run ship --var version=0.3.0`
  ship:
    steps:
      - name: check
        task: check           # reuse the whole check task
      - name: tag
        func: shell
        do: echo "tagging v{{ vars.version }}"
      - name: publish
        func: shell
        do: echo "publishing v{{ vars.version }} to {{ vars.target }}"
        retry:
          max_attempts: 3
          interval: "1s"
          backoff_rate: 2.0

Three things this buys you over a notes.md. The release reuses check instead of re-listing the steps, so you can't ship a build you didn't test. The version is a named input you pass with --var version=0.3.0, not a value you hard-code and forget to bump. And the flaky publish retries on its own — three attempts with backoff — instead of you re-running the command and swearing.

See it before you run it

The other solo superpower is the dry run. You rarely ship, so you never remember exactly what ship does. Instead of reading the file and hoping, ask it:

orchstep run ship --var version=0.3.0 --dry-run

It resolves every variable and prints the exact plan without executing a thing. For a step you run once a month, that preview is the difference between confidence and a held breath. And when you genuinely can't recall the task name:

orchstep menu

A fuzzy picker with single-key hotkeys. Your project becomes self-documenting without you writing docs.

What you gained

Where OrchStep is not the answer

If a one-line Makefile target covers you, use the Makefile — don't add a tool to feel organized. OrchStep starts paying off at the second task, the first named input, or the first time you copy-paste a retry loop. Below that, it's overhead. Be honest about which side of that line your project is on.

Where to go next

• Quick Start — your first workflow in two minutes
• Variables & Outputs — named inputs and --var
• Previewing with Dry Run — see the plan before it runs
• Error Handling — retry, catch, finally

Install is one line and there's no account: drop an orchstep.yml next to your code and run orchstep menu.