boku — YAML task runner
⚠️<br>The boku package name on PyPI is currently squatted. Please<br>install with pip install boku2 or<br>uv tool install boku2 until the name is cleared.<br>Track progress →
Boku (僕 — "servant") reads a YAML file and runs the tasks inside it.<br>One after another. Variables, iteration, dependencies, conditions —<br>all in YAML.
No #!/bin/bash. No tab-indentation rage. No<br>ifeq syntax. Just a list of things to do.
why not bash_
bash
#!/bin/bash<br>for pkg in fzf eza bat; do<br>if command -v brew &>/dev/null; then<br>brew install "$pkg"<br>fi<br>done
boku
variables:<br>packages: [fzf, eza, bat]
tasks:<br>install:<br>if: command -v brew<br>iterate: packages<br>run: brew install {}
a more complex task_
daily.yaml
variables:<br>vault: ~/Documents/Brain/<br>daily: ${vault}Daily/
tasks:<br>date:<br>run: date +%Y-%m-%d<br>save_output: date<br>suppress_output: true
daily_obsidian:<br>if: test -f ${daily}${date}.md<br>run: cat ${daily}${date}.md | grep -E '^- \[ \]'<br>save_output: daily_tasks<br>suppress_output: true
weather:<br>run: curl -s wttr.in/new-york?0T | base64<br>save_output: weather<br>suppress_output: true
day:<br>run: |<br>echo "## Weather"<br>echo "${weather}" | base64 -d<br>echo ""<br>echo "## Today's tasks"<br>echo "${daily_tasks}"
Fetches today's date, pulls Obsidian tasks, gets weather, renders a<br>daily brief.
features_
iterate
Loop over lists. {} becomes each item.
depends_on
Control execution order. Tasks wait.
variables
${var} normal · @{var} masked ·<br>${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?
Most likely because I didn't see the need in it.
Q: Why not Taskfile?
Taskfile is great. It's also a bigger surface area – includes,<br>templating, dotenv, remote schemas. Boku is smaller. If you need<br>less, it's simpler.
Q: Why not just write a Python<br>script?
You could. But then you're writing Python. Boku is for when you<br>want to describe what to run, not how to run it.
Q: Why no parallel execution?
Because I didn't need it, and it would make boku more complex than<br>it needs to be. Sequential is predictable. You can always shell<br>out to & if you want background jobs.
Q: Is this serious?
It's a YAML file that runs commands. Take it as seriously as you<br>take your shell aliases.
for agents_
YAML is unambiguous. LLMs can read, write, and modify boku taskfiles<br>without guesswork. skills/ has step‐by‐step guides for<br>common patterns — give your agent the skills and a taskfile, and it<br>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_
$ pipx install boku2<br>$ uv tool install boku2<br>$ pip install git+https://git.sr.ht/~hxii/boku