Quick Start

Create a Workflow

Scaffold a starter file (available since v0.9.0):

orchstep init

This writes a commented, runnable orchstep.yml and prints the next commands to try. orchstep init --list shows the other templates: env (environment-aware, run with --env) and ci (a build/test/package pipeline). An existing file is never overwritten unless you pass --force.

The generated file is a complete workflow, not a stub - it lints clean and its starter task runs green immediately:

The env template scaffolds a workflow with env_groups and environments already wired, so --env production resolves group and environment overrides out of the box:

The whole loop in motion:

Or write the file by hand - this is the whole shape:

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

Run It

orchstep run greet     # or: orchstep run hello, if you used `orchstep init`

Or pick the task from a keyboard menu:

orchstep menu

The menu shows every task in your workflow with auto-assigned single-keystroke hotkeys. Hit the hotkey to run that task instantly, or arrow keys / / to enter fuzzy search and filter by name or description. f cycles filter modes (all → a-z → public → internal), q quits. Running plain orchstep in a terminal auto-launches the menu; in a CI pipeline or non-terminal context it exits cleanly with an error instead of hanging.

Shell note: OrchStep uses POSIX sh (/bin/sh) by default, so your workflows run on Alpine, distroless containers, and any Linux/macOS system without extra dependencies. On Windows, set type: "gosh" to use the built-in Go-native shell — no bash or WSL needed. See Shell Execution for details.

Add Variables

name: deploy
defaults:
  env: staging
  version: "1.0.0"

tasks:
  deploy:
    steps:
      - name: build
        func: shell
        do: echo "Building v{{ vars.version }} for {{ vars.env }}"
      - name: verify
        func: assert
        args:
          condition: '{{ ne vars.version "" }}'
          desc: "Version must not be empty"

orchstep run deploy
orchstep run deploy --var env=production --var version=2.0.0

Next Steps

• Browse examples for real-world patterns
• Read the function reference to see what's available
• Learn about modules for reusable components