Windmill CLI Commands

The Windmill CLI (wmill) provides commands for managing scripts, flows, apps, and other resources.

Global Options

• --workspace <workspace:string> - Specify the target workspace. This overrides the default workspace.
• --debug --verbose - Show debug/verbose logs
• --show-diffs - Show diff informations when syncing (may show sensitive informations)
• --token <token:string> - Specify an API token. This will override any stored token.
• --base-url <baseUrl:string> - Specify the base URL of the API. If used, --token and --workspace are required and no local remote/workspace already set will be used.
• --config-dir <configDir:string> - Specify a custom config directory. Overrides WMILL_CONFIG_DIR environment variable and default ~/.config location.

Commands

app

app related commands

Options:

• --json - Output as JSON (for piping to jq)

Subcommands:

• app list - list all apps
  • --json - Output as JSON (for piping to jq)
• app get <path:string> - get an app's details
  • --json - Output as JSON (for piping to jq)
• app push [file_path:string] [remote_path:string] - push a local app. With no args, infers the app from the current directory and the remote path from its location relative to wmill.yaml.
• app dev [app_folder:string] - Start a development server for building apps with live reload and hot module replacement
  • --port <port:number> - Port to run the dev server on (will find next available port if occupied)
  • --host <host:string> - Host to bind the dev server to
  • --entry <entry:string> - Entry point file (default: index.ts for Svelte/Vue, index.tsx otherwise)
  • --no-open - Don't automatically open the browser
  • --recording - Frame the app in a shell with a Record button, to capture a replayable session recording of the app under development
• app lint [app_folder:string] - Lint a raw app folder to validate structure and buildability
  • --fix - Attempt to fix common issues (not implemented yet)
• app bundle [app_folder:string] - Bundle a raw app folder to js/css without deploying it
  • --out <dir:string> - Directory to write bundle.js and bundle.css into (default: <app_folder>/dist)
  • --no-minify - Skip minification
• app new - create a new raw app from a template
  • --summary <summary:string> - App summary (short description). Skips the prompt when provided. Triggers non-interactive mode.
  • --path <path:string> - App path (e.g., f/folder/my_app or u/username/my_app). Skips the prompt when provided. Triggers non-interactive mode.
  • --framework <framework:string> - Framework template: react19 | react18 | svelte5 | vue. Skips the prompt when provided. Triggers non-interactive mode.
  • --datatable <datatable:string> - Datatable to wire up. Without this flag in non-interactive mode, no datatable is configured.
  • --schema <schema:string> - Schema to use with --datatable. Created (CREATE SCHEMA IF NOT EXISTS) if it doesn't already exist.
  • --overwrite - Overwrite the target directory if it already exists, without prompting.
  • --no-open-in-desktop - Do not prompt to open the new app in Claude Desktop.
• app generate-agents [app_folder:string] - regenerate AGENTS.md and DATATABLES.md from remote workspace
• app set-permissioned-as <path:string> <email:string> - Set the on_behalf_of_email for an app (requires admin or wm_deployers group)

audit

View audit logs (requires admin)

Subcommands:

• audit list - List audit log entries
• audit get <id:string> - Get a specific audit log entry
  • --json - Output as JSON (for piping to jq)

config

Show all available wmill.yaml configuration options

Options:

• --json - Output as JSON for programmatic consumption

Subcommands:

• config migrate - Migrate wmill.yaml from gitBranches/environments to workspaces format

datatable

datatable related commands

Subcommands:

• datatable list - list all datatables in the workspace
  • --json - Output as JSON (for piping to jq)
• datatable run <sql:string> - run a SQL query on a datatable
  • -n --name <name:string> - Datatable name (default: main)
  • -s --silent - Output only the final result as JSON. Useful for scripting.
• datatable migrate - manage datatable migrations
  • datatable migrate new <name:string> - scaffold a new migration (.up.sql / .down.sql files)
    • -d --datatable <datatable:string> - Target datatable (default: main)
  • datatable migrate up - apply all pending migrations to the main datatable (or one via --datatable)
    • -d --datatable <datatable:string> - Target datatable (default: main)
  • datatable migrate down - roll back the most recent migration on the main datatable (or one via --datatable)
    • -d --datatable <datatable:string> - Target datatable (default: main)
• datatable create [name:string] - register a datatable database in the workspace (default: instance-backed 'main') so scripts can use datatable://
  • --resource <resource:string> - Back the datatable with an existing postgresql resource path instead of the instance database
  • --force - Allow adding to a workspace that already has datatables (fork metadata on existing ones is not preserved)
• datatable serve - Serve all datatables as a Postgres-wire endpoint (psql, DBeaver, pgAdmin); the client picks the datatable via the database name in its connection string
  • --port <port:number> - Port to listen on (default: first free port in 5433-5500)
  • --host <host:string> - Bind address (default: 127.0.0.1)
  • --password <password:string> - Password for Postgres clients (default: generate a random password at startup)
• datatable psql - Start a serve listener and launch psql connected to it
  • -n --name <name:string> - Datatable to connect psql to (default: main)
  • --port <port:number> - Port the proxy listens on (default: first free port in 5433-5500)
  • --host <host:string> - Bind address for the proxy (default: 127.0.0.1)
  • --password <password:string> - Password for the temporary Postgres proxy (default: generate a random password at startup)

dependencies

workspace dependencies related commands

Alias: deps

Subcommands:

• dependencies push <file_path:string> - Push workspace dependencies from a local file

dev

Watch local file changes and live-reload the dev page for preview. Does NOT deploy to the remote workspace — use wmill sync push for that.

Options:

• --includes <pattern...:string> - Filter paths given a glob pattern or path
• --proxy-port <port:number> - Port for a localhost reverse proxy to the remote Windmill server
• --path <path:string> - Watch a specific windmill path (e.g., u/admin/my_script or f/my_flow)
• --no-open - Do not open the browser automatically

docs

Search Windmill documentation.

Arguments: <query:string>

Options:

• --json - Output results as JSON.

ducklake

ducklake related commands

Subcommands:

• ducklake list - list all ducklakes in the workspace
  • --json - Output as JSON (for piping to jq)
• ducklake run <sql:string> - run a SQL query on a ducklake
  • -n --name <name:string> - Ducklake name (default: main)
  • -s --silent - Output only the final result as JSON. Useful for scripting.

flow

flow related commands

Options:

• --show-archived - Enable archived flows in output
• --json - Output as JSON (for piping to jq)

Subcommands:

• flow list - list all flows
  • --show-archived - Enable archived flows in output
  • --json - Output as JSON (for piping to jq)
• flow get <path:string> - get a flow's details
  • --json - Output as JSON (for piping to jq)
• flow push <file_path:string> <remote_path:string> - push a local flow spec. This overrides any remote versions.
  • --message <message:string> - Deployment message
• flow run <path:string> - run a flow by path.
  • -d --data <data:string> - Inputs specified as a JSON string or a file using @ or stdin using @-. A resource argument is the bare string $res: as its whole value, and a variable argument is the bare string $var: — not an object wrapper keyed on $res/$var, and not a plain path.
  • -s --silent - Do not ouput anything other then the final output. Useful for scripting.
  • --tag <tag:string> - Override the worker tag the run is dispatched to (e.g. to route it to dev workers instead of the flow's default tag).
• flow preview <flow_path:string> - preview a local flow without deploying it. Runs the flow definition from local files and uses local PathScripts by default. Pass --step to run only one module in isolation (resolves nested steps inside branchone/branchall/forloopflow/whileloopflow plus the special preprocessor/failure modules; supported step types: rawscript, script, flow).
  • -d --data <data:string> - Inputs specified as a JSON string or a file using @ or stdin using @-. A resource argument is the bare string $res: as its whole value, and a variable argument is the bare string $var: — not an object wrapper keyed on $res/$var, and not a plain path.
  • -s --silent - Do not output anything other then the final output. Useful for scripting.
  • --remote - Use deployed workspace scripts for PathScript steps instead of local files.
  • --step <step_id:string> - Run only the named step instead of the whole flow. Honors --data as the step's args and --remote / local-PathScript resolution the same way the full-flow preview does.
  • --tag <tag:string> - Override the worker tag the preview is dispatched to (e.g. to route it to dev workers instead of the flow's default tag).
• flow new <flow_path:string> - create a new empty flow
  • --summary <summary:string> - flow summary
  • --description <description:string> - flow description
• flow bootstrap <flow_path:string> - create a new empty flow (alias for new)
  • --summary <summary:string> - flow summary
  • --description <description:string> - flow description
• flow history <path:string> - Show version history for a flow
  • --json - Output as JSON (for piping to jq)
• flow show-version <path:string> <version:string> - Show a specific version of a flow
  • --json - Output as JSON (for piping to jq)
• flow set-permissioned-as <path:string> <email:string> - Set the on_behalf_of_email for a flow (requires admin or wm_deployers group)

folder

folder related commands

Options:

• --json - Output as JSON (for piping to jq)

Subcommands:

• folder list - list all folders
  • --json - Output as JSON (for piping to jq)
• folder get <name:string> - get a folder's details
  • --json - Output as JSON (for piping to jq)
• folder new <name:string> - create a new folder locally
  • --summary <summary:string> - folder summary
• folder push <name:string> - push a local folder to the remote by name. This overrides any remote versions.
• folder add-missing - create default folder.meta.yaml for all subdirectories of f/ that are missing one
  • -y, --yes - skip confirmation prompt
• folder show-rules <name:string> - Show default_permissioned_as rules for a folder. Use --test-path to see which rule matches a given item path.
  • --test-path <path:string> - Test which rule matches this item path (e.g. f/prod/jobs/my_script)
  • --json - Output as JSON

generate-metadata

Regenerate stale local locks and script schemas and refresh wmill-lock.yaml content hashes (scripts, flows, apps). Writes local files only, not a deploy. Run it after edits that add or remove imports or change a script's arguments, so the lock, the auto-generated UI schema, and wmill-lock.yaml stay in sync.

Arguments: [folder:string]

Options:

• --yes - Skip confirmation prompt
• --dry-run - Show what would be updated without making changes
• --lock-only - Re-generate only the lock files
• --schema-only - Re-generate only script schemas (skips flows and apps)
• --skip-scripts - Skip processing scripts
• --skip-flows - Skip processing flows
• --skip-apps - Skip processing apps
• --strict-folder-boundaries - Only update items inside the specified folder (requires folder argument)
• --parallel <n:number> - Number of items to process in parallel
• -i --includes <patterns:file[]> - Comma separated patterns to specify which files to include
• -e --excludes <patterns:file[]> - Comma separated patterns to specify which files to exclude

Subcommands:

• generate-metadata rehash [folder:string] - Refresh wmill-lock.yaml content hashes from the on-disk .lock and .script.yaml without re-resolving dependencies or hitting the backend. Use when those files are already correct and only the hashes need updating: bootstrapping missing entries or recovering from hash drift.
  • --skip-scripts - Skip processing scripts
  • --skip-flows - Skip processing flows
  • --skip-apps - Skip processing apps
  • --parallel <n:number> - Number of items to process in parallel
  • -i --includes <patterns:file[]> - Comma separated patterns to specify which files to include
  • -e --excludes <patterns:file[]> - Comma separated patterns to specify which files to exclude

gitsync-settings

Manage git-sync settings between local wmill.yaml and Windmill backend

Subcommands:

• gitsync-settings pull - Pull git-sync settings from Windmill backend to local wmill.yaml
  • --repository <repo:string> - Specify repository path (e.g., u/user/repo)
  • --default - Write settings to top-level defaults instead of overrides
  • --replace - Replace existing settings (non-interactive mode)
  • --override - Add branch-specific override (non-interactive mode)
  • --diff - Show differences without applying changes
  • --json-output - Output in JSON format
  • --with-backend-settings <json:string> - Use provided JSON settings instead of querying backend (for testing)
  • --yes - Skip interactive prompts and use default behavior
  • --promotion <branch:string> - Use promotionOverrides from the specified branch instead of regular overrides
• gitsync-settings push - Push git-sync settings from local wmill.yaml to Windmill backend
  • --repository <repo:string> - Specify repository path (e.g., u/user/repo)
  • --diff - Show what would be pushed without applying changes
  • --json-output - Output in JSON format
  • --with-backend-settings <json:string> - Use provided JSON settings instead of querying backend (for testing)
  • --yes - Skip interactive prompts and use default behavior
  • --promotion <branch:string> - Use promotionOverrides from the specified branch instead of regular overrides
• gitsync-settings status - Report how local changes deploy to the workspace (git push vs wmill sync push)
  • --json-output - Output in JSON format

group

Manage workspace groups

Options:

• --json - Output as JSON (for piping to jq)

Subcommands:

• group list - List all groups in the workspace
  • --json - Output as JSON (for piping to jq)
• group get <name:string> - Get group details and members
  • --json - Output as JSON (for piping to jq)
• group create <name:string> - Create a new group
  • --summary <summary:string> - Group summary/description
• group delete <name:string> - Delete a group
• group add-user <name:string> <username:string> - Add a user to a group
• group remove-user <name:string> <username:string> - Remove a user from a group

hub

Hub related commands. EXPERIMENTAL. INTERNAL USE ONLY.

Subcommands:

• hub pull - pull any supported definitions. EXPERIMENTAL.

init

Bootstrap a windmill project with a wmill.yaml file

Options:

• --use-default - Use default settings without checking backend
• --use-backend - Use backend git-sync settings if available
• --repository <repo:string> - Specify repository path (e.g., u/user/repo) when using backend settings
• --bind-profile - Automatically bind active workspace profile to current Git branch
• --no-bind-profile - Skip workspace profile binding prompt

instance

sync local with a remote instance or the opposite (push or pull)

Subcommands:

• instance add [instance_name:string] [remote:string] [token:string] - Add a new instance
• instance remove <instance:string:instance> - Remove an instance
• instance switch <instance:string:instance> - Switch the current instance
• instance pull - Pull instance settings, users, configs, instance groups and overwrite local
  • --yes - Pull without needing confirmation
  • --dry-run - Perform a dry run without making changes
  • --skip-users - Skip pulling users
  • --skip-settings - Skip pulling settings
  • --skip-configs - Skip pulling configs (worker groups)
  • --skip-groups - Skip pulling instance groups
  • --include-workspaces - Also pull workspaces
  • --folder-per-instance - Create a folder per instance
  • --instance <instance:string> - Name of the instance to pull from, override the active instance
  • --prefix <prefix:string> - Prefix of the local workspaces to pull, used to create the folders when using --include-workspaces
  • --prefix-settings - Store instance yamls inside prefixed folders when using --prefix and --folder-per-instance
• instance push - Push instance settings, users, configs, group and overwrite remote
  • --yes - Push without needing confirmation
  • --dry-run - Perform a dry run without making changes
  • --skip-users - Skip pushing users
  • --skip-settings - Skip pushing settings
  • --skip-configs - Skip pushing configs (worker groups)
  • --skip-groups - Skip pushing instance groups
  • --include-workspaces - Also push workspaces
  • --folder-per-instance - Create a folder per instance
  • --instance <instance:string> - Name of the instance to push to, override the active instance
  • --prefix <prefix:string> - Prefix of the local workspaces folders to push
  • --prefix-settings - Store instance yamls inside prefixed folders when using --prefix and --folder-per-instance
• instance whoami - Display information about the currently logged-in user
• instance get-config - Dump the current instance config (global settings + worker configs) as YAML
  • -o, --output-file <file:string> - Write YAML to a file instead of stdout
  • --show-secrets - Include sensitive fields (license key, JWT secret) without prompting
  • --instance <instance:string> - Name of the instance, override the active instance
• instance connect-slack - Non-interactively connect Slack at the instance level using a pre-minted bot token (xoxb-...). Produces the same artifacts as the UI OAuth flow: global_settings 'slack' row + encrypted f/slack_bot/global_bot_token variable and resource in the admins workspace.
  • --bot-token <bot_token:string> - Slack bot token (xoxb-...)
  • --team-id <team_id:string> - Slack team id
  • --team-name <team_name:string> - Slack team name
  • --instance <instance:string> - Instance profile to connect against (defaults to the active instance)

job

Manage jobs (list, inspect, cancel)

Subcommands:

• job list - List recent jobs
• job get <id:string> - Get job details. For flows: shows step tree with sub-job IDs
  • --json - Output as JSON (for piping to jq)
• job result <id:string> - Get the result of a completed job (machine-friendly)
• job logs <id:string> - Get job logs. For flows: aggregates all step logs
• job cancel <id:string> - Cancel a running or queued job
  • --reason <reason:string> - Reason for cancellation
• job rerun <id:string> - Re-run a completed job with the same args. Prints the new job UUID on stdout.
• job restart <id:string> - Restart a completed flow at a given top-level step. Prints the new flow job UUID on stdout.
  • --step <stepId:string> - Top-level step id to restart the flow from
  • --iteration <n:number> - For a top-level branchall or for-loop step, the iteration to restart at

jobs

Manage jobs (import/export)

Subcommands:

• jobs pull [workspace:string] - Pull completed and queued jobs from workspace
  • -c, --completed-output <file:string> - Completed jobs output file (default: completed_jobs.json)
  • -q, --queued-output <file:string> - Queued jobs output file (default: queued_jobs.json)
  • --skip-worker-check - Skip checking for active workers before export
• jobs push [workspace:string] - Push completed and queued jobs to workspace
  • -c, --completed-file <file:string> - Completed jobs input file (default: completed_jobs.json)
  • -q, --queued-file <file:string> - Queued jobs input file (default: queued_jobs.json)
  • --skip-worker-check - Skip checking for active workers before import

lint

Validate Windmill flow, schedule, and trigger YAML files in a directory, and report script metadata that has no deployable content file

Arguments: [directory:string]

Options:

• --json - Output results in JSON format
• --fail-on-warn - Exit with code 1 when warnings are emitted
• --locks-required - Fail if scripts or flow inline scripts that need locks have no locks
• -w, --watch - Watch for file changes and re-lint automatically

object-storage

Object storage (S3) related commands. Operates on the workspace's default object storage; use --storage to target a configured secondary storage.

Alias: s3

Subcommands:

• object-storage list - List configured object storages for the workspace (default + secondary).
  • --json - Output as JSON (for piping to jq)
• object-storage files [prefix:string] - List files in an object storage. Optionally filter by prefix.
  • --json - Output as JSON (for piping to jq)
  • --max-keys <maxKeys:number> - Page size (default 100)
  • --marker <marker:string> - Pagination marker from a previous response
  • --storage <storage:string> - Secondary storage name (omit for the workspace default)
• object-storage upload <local_path:string> <file_key:string> - Upload a local file to object storage at the given file key.
  • --storage <storage:string> - Secondary storage name
  • --content-type <contentType:string> - Content-Type header to set on the object
  • --content-disposition <contentDisposition:string> - Content-Disposition header to set on the object
• object-storage download <file_key:string> [output_path:string] - Download an object to a local file (or stdout). Default output path is the basename of the file key in the current directory.
  • --storage <storage:string> - Secondary storage name
  • --stdout - Write file contents to stdout instead of a file
• object-storage delete <file_key:string> - Delete an object from object storage. Prompts for confirmation unless --yes is set.
  • --storage <storage:string> - Secondary storage name
  • --yes - Skip the confirmation prompt
• object-storage move <src_file_key:string> <dest_file_key:string> - Move an object within the same storage (rename or relocate by key).
  • --storage <storage:string> - Secondary storage name
• object-storage info <file_key:string> - Show metadata (size, mime, last-modified) for an object.
  • --json - Output as JSON (for piping to jq)
  • --storage <storage:string> - Secondary storage name
• object-storage preview <file_key:string> - Preview the contents of an object (text/CSV). Use --bytes-from / --bytes-length to peek at a slice of binary files.
  • --storage <storage:string> - Secondary storage name
  • --mime <mime:string> - Override the detected mime type (e.g. text/csv)
  • --bytes-from <bytesFrom:number> - Start offset in bytes
  • --bytes-length <bytesLength:number> - Number of bytes to read
  • --csv-separator <csvSeparator:string> - CSV column separator (default ,)
  • --csv-header - Treat the first CSV row as a header

pipeline

inspect asset-driven pipelines (scripts marked // pipeline, wired by // on <spec> annotations)