wmill-safety — Windmill CLI Safety Guard

Safety-first skill for the Windmill wmill CLI. Classifies commands by risk, enforces pre-flight checklists for destructive operations, and optionally installs hard-enforcement hooks.

This skill complements the skills generated by wmill init — those teach how to write Windmill scripts and flows. This skill governs how to safely execute CLI operations.

Before Any Operation

Always verify your active workspace first:

wmill workspace whoami

Confirm the workspace and user are correct before proceeding. Running commands against the wrong workspace is the most common source of accidental damage.

Risk Tiers

Every wmill command falls into one of three tiers. Know which tier you're in before executing.

Safe — No Restrictions

Read-only, list, and inspect operations. Run freely.

Category	Commands
Workspace	`workspace list`, `workspace whoami`, `workspace list-remote`, `workspace list-forks`
Scripts	`script list`, `script get`, `script history`, `script show-version`, `script preview`
Flows	`flow list`, `flow get`, `flow history`, `flow show-version`, `flow preview`
Apps	`app list`, `app get`, `app lint`
Resources	`resource list`, `resource-type list`, `resource-type get`
Variables	`variable list`
Jobs	`job list`, `job get`, `job logs`, `job result`
Schedules	`schedule list`, `schedule get`
Triggers	`trigger list`, `trigger get`
Folders	`folder list`, `folder get`
Admin	`token list`, `group list`, `group get`, `audit list`, `audit get`
System	`version`, `init`, `lint`, `workers`, `queues`, `docs`
Other	`generate-metadata --dry-run`, `instance whoami`

Caution — Inform User, Proceed With Care

Operations that modify local state, have mild side effects, or may expose sensitive values. State what you're about to do before running.

Command	Risk
`wmill sync pull`	Overwrites local files — always use in a git-tracked directory
`wmill workspace add/switch/remove`	Changes local workspace configuration
`wmill workspace bind/unbind`	Modifies wmill.yaml branch bindings
`wmill generate-metadata`	Modifies local lock and schema files
`wmill script new/bootstrap`	Creates local files
`wmill flow new/bootstrap`	Creates local files
`wmill folder new`	Creates local folder structure
`wmill dev`	Starts dev server that auto-pushes changes to remote
`wmill variable get`	May expose credential values — confirm with user
`wmill resource get`	May expose credential values — confirm with user
`wmill instance get-config`	Has `--show-secrets` flag that exposes sensitive fields

Danger — Pre-Flight Checklist Required

Remote-destructive operations. You MUST run the full pre-flight checklist before executing any of these.

Command	Impact
`wmill sync push`	Deletes remote items not present locally
`wmill instance push`	Overwrites instance-level config (users, settings, worker groups)
`wmill script push`	Overrides remote script version
`wmill flow push`	Overrides remote flow version
`wmill app push`	Overrides remote app version
`wmill resource push`	Overrides remote resource
`wmill variable push`, `variable add`	Overrides remote variable value
`wmill schedule push`	Overrides remote schedule config
`wmill trigger push`	Overrides remote trigger config
`wmill folder push`	Overrides remote folder config
`wmill script run`, `flow run`	Executes code on remote Windmill instance
`wmill user add/remove`	Modifies user accounts
`wmill schedule enable/disable`	Activates or deactivates scheduled jobs
`wmill job cancel`	Kills a running job
`wmill token create/delete`	Manages API tokens
`wmill group create/delete`	Creates or deletes groups
`wmill group add-user/remove-user`	Modifies group membership
`wmill workspace delete-fork`	Deletes a forked workspace

Banned Flags

Never use these flags under any circumstances:

Flag	Reason
`--plain-secrets`	Exposes secrets as unencrypted text
`--yes` on `sync push`	Bypasses confirmation prompt that shows what will be deleted
`--show-diffs`	May reveal secret values in terminal output
`--show-secrets` on `instance get-config`	Exposes license key, JWT secret

Pre-Flight Checklists

Sync Push

This is the most dangerous routine operation. sync push deletes remote items that don't exist locally.

Confirm working directory is git-tracked: git status
Confirm wmill sync pull was run first this session
Run wmill sync push --dry-run and show the user what will be created, modified, and deleted
If any deletions appear, explicitly warn: "This will delete N remote items" and list them
Get explicit user approval before running the real push
Never use --yes, --plain-secrets, or --show-diffs

# Step 1: Verify git state
git status

# Step 2: Pull first
wmill sync pull

# Step 3: Dry run
wmill sync push --dry-run

# Step 4-5: Review output with user, get approval

# Step 6: Push (only after approval)
wmill sync push

Instance Push

Run wmill instance push --dry-run and show results
Warn: "This overwrites instance-level config (users, settings, worker groups)"
Get explicit user approval

Individual Push (script, flow, app, resource, variable, schedule, trigger, folder)

State what will be overridden on remote (path and type)
Get explicit user approval
Never use --plain-secrets

Remote Execution (script run, flow run)

State what script/flow will execute and on which workspace
Show the input data if any (-d flag value)
Get explicit user approval

User and Group Management

State the exact action (add/remove user, create/delete group, add/remove member)
For user add --superadmin, explicitly warn: "This grants superadmin privileges"
Get explicit user approval

Token, Schedule, and Job Operations

State the action and target
Get explicit user approval

Optional: Hook Installation

The safety rules above are guidance that Claude follows voluntarily. For hard enforcement that blocks dangerous commands even if bypassed, install the hooks from the sieteunoseis/cmds.cc repository.

Source: hooks/windmill-safety

Available Hooks

Hook	Default	Purpose
Require pull before push	On	Blocks `sync push` unless `sync pull` ran first this session
Track sync pull	On	Marker file that enables the pull-before-push guard
Block --yes on sync	On	Prevents bypassing confirmation prompts
Block --plain-secrets	On	Prevents secret exposure as unencrypted text
Block script/flow execution	On	Prevents remote code execution without approval
Block script push without review	Off	Requires explicit approval for individual script pushes
Block reading variables/resources	Off	Prevents credential exposure via get commands

Installation

Download claude-hooks.json from the repo and merge the hooks into your .claude/settings.json under the hooks key. Each hook can be individually enabled or disabled.

Creating Custom Hooks

You are encouraged to create your own hooks for org-specific policies. Examples:

Block pushes to production workspaces
Require specific naming conventions
Enforce --skip-secrets on all sync operations
Block user add --superadmin

See the existing hooks in claude-hooks.json for the pattern. Hooks use PreToolUse events on the Bash matcher with jq to inspect command arguments.

Quick Reference — Common Safe Operations

Workspace

wmill workspace whoami          # show active user and workspace
wmill workspace list            # list local workspace profiles
wmill workspace list-remote     # list remote workspaces you can access
wmill workspace switch <name>   # switch active workspace

Inspect Scripts, Flows, Apps

wmill script list               # list all scripts
wmill flow list                 # list all flows
wmill app list                  # list all apps
wmill script get <path>         # show script details
wmill script history <path>     # show version history

Jobs

wmill job list                  # list recent jobs
wmill job get <id>              # inspect a job
wmill job logs <id>             # view job logs
wmill job result <id>           # get job output

Resources and Variables

wmill resource list             # list all resources
wmill variable list             # list all variables

Validation

wmill lint                          # validate YAML files
wmill generate-metadata --dry-run   # preview metadata changes

System

wmill version                   # show CLI version
wmill workers                   # list workers by group
wmill queues                    # list queues with metrics

For full CLI reference including all flags and subcommands, use the cli-commands skill generated by wmill init.

Integration

This skill works alongside the skills generated by wmill init:

cli-commands — full CLI reference (flags, subcommands, options)
write-script-* — language-specific script writing guidance
write-flow — flow building guidance
resources / triggers / schedules — infrastructure configuration

This skill adds the safety layer that those skills don't cover.