Interactive, typed, local-first workflows for developers.
Turn the scripts, checklists, and prompts around your code into readable YAML you can run,
validate, share, and reuse.
Install · Quick start · Gallery · Built-ins · Docs
- Interactive when you want it, scriptable when you don't. Prompts, choices, file pickers,
diff reviews, tables, and live dashboards, all skippable with
--varfor CI and scripts. - Typed state, not string soup. Step outputs, JSON, TOML, YAML, JSONPath, semantic versions, and list or object transforms stay typed between steps.
- Real control flow. Conditions, retries and polling, parallel DAGs,
foreachandmatrix,try/catch, guaranteed cleanup, early returns, and cron schedules. - Fewer platform-specific scripts. Built-in steps cover Git, GitHub, HTTP, files, Docker, processes, Lua, and coding agents.
- Fails before it runs. Validation catches unknown steps, variables, and references with
source locations and suggestions. Use
--dry-runandwuko treeto see what will happen.
Wuko is not a GitHub Actions runtime. It is for local and interactive development automation; a CI job can invoke Wuko, but the two workflow formats are separate.
brew install --cask up2jj/tap/wuko # macOS
go install github.com/up2jj/wuko@latest # Go 1.26 or newer
nix profile add github:up2jj/wuko # Linux or macOS, with Nix flakes enabledOn Nix releases older than 2.26, use nix profile install; to try Wuko without installing, run
nix run github:up2jj/wuko -- --help.
Create .wuko/workflows/check.yaml in your project:
version: 1
name: check
description: Run the project checks
vars:
package: ./...
steps:
- id: tests
type: shell
with:
command: go
args: [test, "{{ .vars.package }}"]
- id: summary
type: shell
with:
command: printf
args: ["tests exited with %s\n", "{{ .steps.tests.exit_code }}"]Then run it:
wuko # pick from every discovered workflow
wuko run check # run by name
wuko run check --var package=./cmd/... # override a variable
wuko run check --dry-run # validate and preview without running
wuko run check --cpus 1.5 --memory 512MiB # shared local CPU and memory budgetTo save defaults for bare wuko, add a wuko.yml to the current directory; explicit flags
override it and --no-config ignores it. See Local configuration.
The binary bundles a reference with a complete example for every built-in:
wuko reference step shell
wuko reference example set basic --format yaml
wuko help run --format jsonNext, the Getting started guide walks from here to prompts, retries, parallel work, and composition.
Every recording is generated from an offline workflow in docs/demos/gallery.
See all of them, with their YAML, in the gallery.
Ask, then act. Interactive steps store answers in variables; pass --var approved=true to skip
the prompt. Interactive steps →
- id: approval
type: tui_confirm
with:
variable: approved
message: Deploy to production?
default: false
- id: deploy
type: shell
if: vars.approved
with: {command: ./deploy, args: [production]}Retry flaky work. attempt bounds, retries, or polls any block of steps.
Attempts →
- id: publish
attempt:
max_attempts: 4
initial_delay: 1s
backoff_multiplier: 2
steps:
- {id: upload, type: shell, with: {command: ./upload}}Fan out. Run a dependency graph in parallel, or every combination of a matrix. Workflow controls →
- concurrent:
steps:
- {id: deps, type: shell, with: {command: go, args: [mod, download]}}
- {id: lint, needs: [deps], type: shell, with: {command: golangci-lint, args: [run]}}
- {id: test, needs: [deps], type: shell, with: {command: go, args: [test, ./...]}}Work with typed data. Decode, query, reshape, and version values without jq or sed.
Data steps →
- id: config
type: decode
with: {format: json, path: package.json}
- id: next
type: semver
with: {operation: increment, version: "{{ .steps.config.value.version }}", part: minor}Recover and clean up. try/catch handles failures; finally always runs.
Finally cleanup →
steps:
- id: release
try:
steps: [{id: deploy, type: shell, with: {command: ./deploy}}]
catch:
steps: [{id: rollback, type: shell, with: {command: ./rollback}}]
finally:
- {id: cleanup, type: shell, with: {command: ./cleanup}}| Area | Built in |
|---|---|
| Interactive | tui_form, tui_input, tui_password, tui_choice, tui_date, tui_path, tui_confirm, tui_review, tui_table, dashboard, browser forms |
| Data | set, template, transform, decode, jsonpath, edit, markdown_edit, extract, semver, time, assert, check, print, import_vars, key_value, changed |
| Git and GitHub | git_diff, git_log, git_commit, git_conventional_commit, worktrees, squash, rebase, merge, branch checks, github_pr, github_release, github_actions |
| Files and system | file, glob, scaffold, watch, log_wait, temp, cache, require_tool, tcp_probe, multiplexer |
| Network, processes, and automation | http, docker, shell (including scripted PTY sessions and the Node and Bash SDKs), process, process_call, lua |
| Controls | if, attempt, concurrent, foreach, batch, matrix, loop, try/catch, cancel_on, observe, return, defer, finally, cron, executor |
| Composition | depends_on, run_workflow, targets, require, uses composite actions, once |
- GitHub Actions. Run any workflow in CI with annotations, a job summary, and typed outputs:
uses: up2jj/wuko@v0.22.0. GitHub Actions guide → - Shell commands. Create
./checkwithwuko shim create check, or install it on PATH withwuko shim install check. Usewuko shim create check --inlineto embed the workflow in the script. Expose a project's workflows from anywhere withwuko shim install --project ./automation. Workflow shims → - Git hooks. Bind workflows to
pre-commit,commit-msg, orpre-pushwithwuko git hook init. Git hooks → - Nix and devenv. Pin Wuko in a project shell and run steps in devenv environments. Nix and devenv guide →
- Remote servers. Keep Wuko local and run a block's commands and file operations on a Linux server. SSH executor →
- Coding agents. Hand tasks to Claude or Codex with
shellsteps andstdin, install Wuko's authoring skills withwuko agent install, and give agents structured discovery and execution reports. Agent guide → · Calling agents → - Remote workflows and marketplaces. Run workflows from GitHub, reuse actions from private
repositories, and install packages with
wuko install. Discovery → · Marketplaces → - Plugins. Add namespaced steps, executors, and helpers in any language. Executable plugins →
- Start here: Getting started · CLI cheatsheet · Reference · Validation · Gallery
- Write workflows: Templates · Functions · Workflow controls · Early return · Cleanup with finally · Variable imports · Secrets · Browser forms
- Steps: Interactive · Data · System · Automation · Text extraction · Filesystem operations · Docker operations
- Run and share: Workflow discovery · Execution and composition · Executor scopes · Graceful shutdown · Persistent Git worktrees · Git change recipes
- Extend: Executable plugins · Plugin protocol v1, v2, v4
Workflows, composite actions, and plugins are trusted code: shell, Lua, Docker, and HTTP steps can reach anything Wuko can. Review publishers and pin remote sources. Read the trust model before running workflows from someone else.
Bug reports and pull requests are welcome. See CONTRIBUTING.md for the development loop and Screenshot and demo maintenance for re-recording the gallery.






