Documentation

Everything WF does, in the order it does it. Run every command from the folder that holds your .wf files: WF only reads the current directory.

1. Install

WF ships as 5 standalone binaries. Download the one for your platform from the latest release:

Linux and macOS: make it executable and put it in your PATH.

$ chmod +x wf-linux-amd64
$ sudo mv wf-linux-amd64 /usr/local/bin/wf
$ wf --version          # prints: wf version 2.1.0
$ wf                    # prints the WF logo and your workflows

Windows: rename the file to wf.exe and place it in a folder listed in your PATH.

2. Quick start

Create a file ending in .wf at your project root, for example deploy.wf:

[build] # Build the application
echo "Building the application..."
run npm install
run npm run build

[deploy] # Build and start the containers
set ENV=production
wf build
docker_compose up -d
notify_success "Deployed in ${ENV}"

Then run:

$ wf                    # lists build and deploy, with their comments
$ wf deploy             # runs deploy, and build as a sub-workflow
$ wf build              # runs build on its own

3. Writing .wf files

WF reads every file ending in .wf in the current folder (not in sub-folders). Each line is trimmed, then:

1. An empty line, or a line starting with #, is ignored.
2. A line starting with [ opens a section. The name is what is between [ and ]. Text after # on that line becomes the section description, shown by wf. Between ] and #, only the log=<file> option is allowed (see Run history).
3. Any other line is a command of the current section. Its first word is the command keyword, case-insensitive: set, SET and Set are the same.

Lines written before the first section form a section called main, run with wf main. A section with no command is dropped. wf lists the sections in the order they are written, file by file in alphabetical order.

WF does not check a file before running it. Each line is read when its turn comes; see Errors and exit codes.

4. Running wf

$ wf                    # logo, then the list of sections and their descriptions
$ wf <section>          # runs that section
$ wf help <section>     # shows the description of one section
$ wf --version          # prints the WF version

Section names are case-sensitive here: [Deploy] runs with wf Deploy, not wf deploy. An unknown name prints No help topic for '<name>' and exits with code 3. If the folder has no .wf file, WF also prints No workflow files found.

The section runs under a full-width WORKFLOW: <NAME> header and ends with Workflow '<name>' completed in <duration>.

5. Variables

Before running a line, WF replaces every ${NAME} it knows:

set APP=my-app
set IMAGE=registry.local/${APP}
echo "Building ${IMAGE} from ${CURRENT_PATH}"

set prints Variable NAME set to value. The name is what comes before the first =, the value is everything after it, including other = signs. Spaces around the name and the value are removed: set DSN = mysql://db?x=1 works. An empty name or value stops WF with Invalid set command.

load_env

load_env .env
echo "Connecting to ${DATABASE_URL}"

Reads the file and sets one WF variable per NAME=value line, like set. Empty lines, lines starting with # and lines without = are skipped. One pair of quotes around the value is removed ("..." or '...'). An empty value is allowed. ${...} inside the file is not replaced. WF prints how many variables were loaded, never their values. A missing file stops WF.

Variables are shared by every workflow of a run: a variable set in a sub-workflow is still there after it returns. An unknown ${NAME} is left in the line as is. set can also override CURRENT_PATH or IP_LOCAL.

WF variables live in WF only. They are not environment variables: a program started with run does not see them. It does see the environment WF itself was started with.

6. run and docker_compose

run composer install --no-dev
run php bin/console cache:clear
docker_compose up -d --build

run starts a program directly, without a shell. The line is split on spaces: the first word is the program, found in your PATH, the others are its arguments. Quotes work like in a terminal:

A quote that is never closed stops WF with Missing closing quote. A lone apostrophe opens a quote too: write "it's". Backslashes are plain text, so Windows paths like C:\Users\me work as written. Pipes (|), redirections (>), &&, globs (*), ~ and $VAR are passed as plain text.

Need shell features? Put them in a script and run the script:

run sh scripts/backup.sh
run cmd /c dir          # Windows built-in commands go through cmd

WF prints the command, frames its output, then shows its duration:

╭─ ▶ composer install --no-dev
│  Installing dependencies from lock file
│  ...
╰─ ✔ 3.4s

If the program cannot be found or exits with a non-zero code, WF prints ✘ Failed in <duration> and Command failed, then stops with exit code 1.

docker_compose <args> works like run, with docker compose <args> when the Compose plugin answers, or docker-compose <args> otherwise. The check is done once per run.

7. Files and folders

These commands are written in Go and do not depend on the system tools. Paths are relative to the folder where wf was started, and cannot contain spaces, except for touch.

remove dist
mkdir dist
write .env.local APP_SECRET=${GENERATE_SECRET}
move build/app dist/app

On Windows, set_permissions can only toggle the read-only flag: a mode without the owner write bit (like 0444) makes files read-only, any other mode makes them writable.

8. Messages

echo "Plain message"
notify "Same as echo"
notify_info "Blue INFO label"
notify_success "Green SUCCESS label"
notify_warning "Yellow WARNING label"
notify_error "Red ERROR label"
sync_time                  # prints: System time: 2026-10-13 12:18:50 CEST

Messages are printed in the terminal; there is no desktop notification. Double quotes around the message are removed. notify_error only prints: the workflow continues. To stop, use exit or let a run fail.

sync_time prints the current system time and zone. It does not change the clock.

9. Checks and pauses

[deploy]
require docker git
confirm "Deploy to production?"
docker_compose up -d
sleep 5
docker_compose exec php bin/console doctrine:migrations:migrate -n

require <program...> checks that each program can be found in the PATH, and prints <program> found. A missing one stops WF with <program> is required but was not found in PATH. Put it at the top of a section, so nothing runs on a machine that is not ready.

sleep <seconds> waits a whole number of seconds, for example while a container starts.

confirm "<question>" prints the question followed by [y/N] and waits for an answer. y or yes, in any case, continues. Anything else, including just pressing Enter, stops WF with Cancelled and exit code 1.

10. Sub-workflows and exit

[deploy]
wf build
wf migrate
docker_compose up -d

wf <section> runs another section, then comes back to the next line. Sub-workflows can call other sub-workflows. Each level is indented in the output:

  ╭── 📦 Sub-Workflow: build
  ...
  ╰── ✔ Completed in 9.8s

Any section of any .wf file in the folder can be called. A name that does not exist stops WF with Workflow '<name>' not found. A section that calls itself, directly or through another one, never ends.

exit stops WF immediately, including every parent workflow, with exit code 0. exit <code> uses that code instead: exit 1 stops on purpose and marks the run as failed. A code that is not a number stops WF with Invalid exit code.

11. Run history

[deploy] log=deploy.log # Deploy the application
run composer install --no-dev
docker_compose up -d

The log=<file> option in a section header keeps a trace of every run of that section. When the run ends, WF appends one line to the file, created if needed:

2026-10-14 09:12:03 | deploy          | SUCCESS   | 12.4s   | fady@prod-01
2026-10-15 10:05:31 | deploy          | FAILED    | 3.1s    | fady@prod-01 | run composer install --no-dev
2026-10-16 18:30:12 | deploy          | CANCELLED | 2s      | marc@prod-01
2026-10-16 18:41:57 | build           | EXIT 3    | 900ms   | ci@runner-2

Columns are aligned for section names up to 15 characters; a longer name simply pushes the rest of its line.

Header rules

The option sits between ] and the comment, written exactly log=<file>. WF checks every header when it loads the .wf files, before anything runs, and refuses to start on any mistake:

The log belongs to the section you launch, and covers the whole run, sub-workflows included. A log= on a section called with wf <section> is not used; it only applies when that section is launched directly. Without log=, no file is written. A run stopped with Ctrl+C is not logged. Decide yourself whether the log file goes in Git or in .gitignore.

12. Errors and exit codes

WF stops at the first error. Lines already run stay done: there is no rollback.

An unknown command keyword prints Unknown command or invalid syntax : <line>. Since lines are checked when they run, a typo at the end of a section only shows up after the lines above it have run.

13. Git and CI

Commit your .wf files: they are your project's runbook. WF writes nothing besides what your commands create.

In CI or on a server, download the binary and run a section:

$ curl -fsSL -o /usr/local/bin/wf https://github.com/michelware/wf/releases/latest/download/wf-linux-amd64
$ chmod +x /usr/local/bin/wf
$ wf deploy

The exit code of wf tells your CI whether the workflow succeeded.