boku — YAML task runner

$ boku run deploy█

Write what to run. Not how. Boku reads your YAML, runs your tasks, gets out of the way.

what

Boku (僕 — "servant") reads a YAML file and runs the tasks inside it. One after another. Variables, iteration, dependencies, conditions — all in YAML.

No #!/bin/bash. No tab-indentation rage. No ifeq syntax. Just a list of things to do.

why not bash_

bash

#!/bin/bash
for pkg in fzf eza bat; do
  if command -v brew &>/dev/null; then
    brew install "$pkg"
  fi
done

→

boku

variables:
  packages: [fzf, eza, bat]

tasks:
  install:
    if: command -v brew
    iterate: packages
    run: brew install {}

a more complex task_

variables:
  vault: ~/Documents/Brain/
  daily: ${vault}Daily/

tasks:
  date:
    run: date +%Y-%m-%d
    save_output: date
    suppress_output: true

  daily_obsidian:
    if: test -f ${daily}${date}.md
    run: cat ${daily}${date}.md | grep -E '^- \[ \]'
    save_output: daily_tasks
    suppress_output: true

  weather:
    run: curl -s wttr.in/new-york?0T | base64
    save_output: weather
    suppress_output: true

  day:
    run: |
      echo "## Weather"
      echo "${weather}" | base64 -d
      echo ""
      echo "## Today's tasks"
      echo "${daily_tasks}"

Fetches today's date, pulls Obsidian tasks, gets weather, renders a daily brief.

features_

feature	explanation
iterate	Loop over lists. `{}` becomes each item.
depends_on	Control execution order. Tasks wait.
variables	`${var}` normal · `@{var}` masked · `${env:VAR}` env.
save_output	Capture output into a variable for later tasks.
if	Shell condition. Skip tasks that don't need to run.
on_success	Run a command when the task succeeds.
on_failure	Run a command when the task fails.
dry_run	`boku run ‐d` previews without executing.
fail_fast	Abort remaining tasks on first failure.

faq_

Q Why no [X] feature?

A Most likely because I didn't see the need in it.

Q Why not Taskfile?

A Taskfile is great. It's also a bigger surface area – includes, templating, dotenv, remote schemas. Boku is smaller. If you need less, it's simpler.

Q Why not just write a Python script?

A You could. But then you're writing Python. Boku is for when you want to describe what to run, not how to run it.

Q Why no parallel execution?

A Because I didn't need it, and it would make boku more complex than it needs to be. Sequential is predictable. You can always shell out to & if you want background jobs.

Q Is this serious?

A It's a YAML file that runs commands. Take it as seriously as you take your shell aliases.

for agents_

YAML is unambiguous. LLMs can read, write, and modify boku taskfiles without guesswork. skills/ has step‐by‐step guides for common patterns — give your agent the skills and a taskfile, and it can add tasks, change dependencies, or create new workflows.

01‐quick‐start.md
02‐iteration‐patterns.md
03‐task‐dependencies.md
04‐variables‐and‐secrets.md
05‐conditionals‐and‐helpers.md

install_

Run one of these in your favorite terminal.

src	cmd	cpy
pipx	`pipx install boku2`
uv	`uv tool install boku2`
source	`pip install git+https://git.sr.ht/~hxii/boku`