.. SPDX-License-Identifier: copyleft-next-0.3.1

==================
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 CLI: https://www.windmill.dev/docs/advanced/cli

``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``:

.. code-block:: console

   $ nix develop --command wmill --version

Connecting
==========

Point the CLI at the local instance once it is running (see
:doc:`/deployment/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:

.. code-block:: console

   $ 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 commands
are just ``wmill sync push``. A fresh instance seeds only a ``starter``
workspace, so ``--create`` adds ``kdevops``. 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.

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
:doc:`/reference/wmill-yaml`, the round-trip has no diff:

.. code-block:: console

   $ wmill sync pull          # instance -> files
   $ nix run .#reflow         # keep descriptions as clean literal blocks
   $ wmill sync push          # files -> instance
   $ 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 ``wmill sync push --yes``, 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:

.. code-block:: console

   $ wmill dev --path f/qsu/boot

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

.. _dev and preview: https://www.windmill.dev/docs/advanced/cli/dev-preview

Generated content
=================

:src:`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.