Working with wmill#

wmill is the Windmill command-line client. It moves workspace content between the running instance and this repository, where git is the source of truth. See the upstream wmill CLI documentation for the full command set.

wmill is provisioned from Nix, pinned to the server version, not a host install. Enter the development shell with nix develop to put it on PATH, or prefix a single command with nix develop --command:

host#

$ nix develop --command wmill --version

Connecting#

Point the CLI at the local instance once it is running (see Nix to bring it up). The CLI and the API talk to the server directly on 127.0.0.1:8002 (plain HTTP); 127.0.0.1:8000 is caddy’s HTTPS front for the browser, so a request there over http:// fails. wmill logs in through a browser or a pasted token, and a host with no desktop has neither, so fetch one token from the seeded superadmin (admin@windmill.dev / changeme on a fresh instance); wmill does the rest, --create making the workspace:

$ url=http://localhost:8002
$ token=$(curl --silent --request POST "$url/api/auth/login" \
    --header 'Content-Type: application/json' \
    --data '{"email":"admin@windmill.dev","password":"changeme"}')
$ wmill workspace add kdevops kdevops "$url/" --token "$token" --create

The token is saved to ~/.config/windmill/remotes.ndjson, so later deploys need no re-auth; run them through the deploy-* apps (Deploying). A fresh instance seeds only a starter workspace, so --create adds kdevops; add staging the same way. Change that default password after the first login, and mint a durable token with wmill token create if you want one. wmill init writes AI-assistant context and a few editor files that are git-ignored; it is optional.

Deploying#

Two workspaces share the instance: kdevops for production and staging for work in progress. Deploy through the deploy apps, not a bare wmill sync push:

$ nix run .#deploy-staging     # everything -> staging, for live testing
$ nix run .#deploy-kdevops     # the promoted subset -> production

New or untested flows go to staging and run against live guests there. deploy-kdevops withholds a staging-only set (listed in nix/apps/default.nix) so kdevops carries only promoted work; a bare wmill sync push to kdevops would re-add it. Promote a flow by dropping its entry from that list. See Staging for the model.

Two workflows#

The project supports two ways to work, and a contributor may choose either.

Bidirectional (recommended)#

Edit in the Windmill UI or on disk, then reconcile through git. Because the files are kept in the canonical form described in Workspace YAML format, the round-trip has no diff:

$ wmill sync pull          # instance -> files
$ nix run .#reflow         # keep descriptions as clean literal blocks
$ nix run .#deploy-kdevops # files -> production
$ git add <paths> && git commit --signoff

This unlocks the full engine: UI editing, wmill dev, and a real pull.

Push-only#

Hand-author the YAML on disk, deploy with nix run .#deploy-kdevops, and never pull. This preserves hand-tuned formatting but does not capture UI edits back to git. Prefer the bidirectional flow unless you have a reason not to.

Previewing a flow#

wmill dev opens a live page that renders a local flow or script and writes UI edits straight back to disk, one flow at a time, which is gentler than a bulk pull:

$ wmill dev --path f/qsu/boot

See the dev and preview documentation for wmill dev and wmill flow preview.

Generated content#

f/qsu/bringup.flow/flow.yaml is generated by scripts/gen-bringup.py and is never pulled; regenerate it with python3 scripts/gen-bringup.py after changing a source subflow.