Dev & Preview

The CLI can run scripts and flows against a remote workspace without deploying them, and it can serve a live-reload dev page that mirrors your local files. This is useful for iterating on local files, validating codebase scripts, or testing flow / app changes with local inline script modifications.

wmill dev

wmill dev starts a local live-reload server and opens a Windmill dev page that renders your local flow, script, or raw app. Edits on disk reload the page; edits in the page round-trip back to the local files (flow.yaml, inline scripts, app.yaml, etc.).

wmill dev [--path <wmill_path>] [--proxy-port <port>] [--no-open]

When invoked from inside a *__flow/ folder, wmill dev auto-detects the wm path. When invoked from a workspace root with no --path, the dev page shows a workspace picker — flows, scripts, and raw apps grouped by folder / user, with search and a kind filter.

Run modes

• Direct (default): a WebSocket server on a random port. The dev page lives on the remote workspace and connects back to localhost over WebSocket for live reload. This is the mode the VS Code extension iframe and a regular browser tab use.
• Proxy (--proxy-port <port>): a reverse proxy at http://localhost:<port>/ that 302-redirects / to the remote dev page with workspace, auth token, and --path baked in, and tunnels other HTTP / WebSocket traffic to the remote workspace. This is the mode Claude Code's port-detection preview pane uses.

Options

Option	Description
--path <wmill_path>	Open a specific flow, script, or raw app instead of the workspace picker.
--proxy-port <port>	Run in proxy mode on the given port; needed for Claude Code's preview pane.
--no-open	Don't open the browser; print the URL so the caller (e.g. an AI agent) can hand it to you.

Examples

# Workspace picker
wmill dev

# Jump straight into a flow
wmill dev --path f/my_flows/etl

# Auto-detected when run from inside a flow folder
cd f/my_flows/etl__flow && wmill dev

# Proxy mode for Claude Code's preview pane
wmill dev --proxy-port 4000 --path f/my_flows/etl

Round-trip editing

Editing a flow or script from the dev page writes back to disk:

• flow.yaml is rewritten only when content actually differs.
• Inline scripts (.py, .ts, .bun.ts, .go, .sh, etc.) are kept in sync.
• PathScript references (modules with type: 'script' and a path:) survive the round-trip.
• Fixture files inside the flow folder (README.md, data.json, .env, etc.) are preserved.

When --path is set, edits to other files don't push to the page, so you can keep working on unrelated files in the same workspace folder.

Data pipelines

Pipelines have their own analog: wmill pipeline dev watches a folder of // pipeline scripts and live-previews the pipeline graph in the browser on every save. See Pipelines (CLI).

wmill script preview

Preview a local script file against the remote workspace. Supports both regular scripts and codebase scripts (which are bundled before running).

wmill script preview <path> [options]

Options

Option	Description
-d, --data <data>	Inputs as a JSON string, @filename, or @- for stdin.
-s, --silent	Only output the final result (no logs, useful for scripting).
--tag <tag>	Override the worker tag the preview is dispatched to, instead of the script's default tag. Useful to test changes on specific workers (for example dev workers) before deploying.

Examples

# Regular script
wmill script preview u/admin/my_script.ts --data '{"x": 5}'

# Route the preview to dev workers instead of the script's default tag
wmill script preview u/admin/my_script.ts --data '{"x": 5}' --tag dev

# Codebase script (bundled before preview)
wmill script preview f/codebase_test/my_script.ts --data '{"x": 7}'

# Silent mode for piping
wmill script preview f/scripts/hello.ts -d '{"n":3}' --silent | jq

wmill flow preview

Preview a local flow against the remote workspace. The flow definition is read from the local .flow / __flow folder — any changes to inline scripts are picked up without deploying.

wmill flow preview <path> [options]

Options

Same -d, --data, -s, --silent, and --tag options as script preview. --tag overrides the worker tag the preview is dispatched to (and is threaded through to individual steps when combined with --step).

Example

wmill flow preview f/my_flows/etl__flow --data '{"date":"2026-01-01"}'

# Route the preview to dev workers instead of the flow's default tag
wmill flow preview f/my_flows/etl__flow --data '{"date":"2026-01-01"}' --tag dev

Use wmill dev when you want a live UI that round-trips edits back to disk; use wmill flow preview when you want a one-shot run with a specific payload.