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: /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
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)
Subcommands:
pipeline list - list pipeline folders in the workspace
--json - Output as JSON (for piping to jq)
pipeline show <folder:string> - render a pipeline folder's DAG (sources, lineage, subscriptions) in the terminal
--json - Output the raw asset graph as JSON
--local - Build the graph from local working-tree files (// pipeline scripts) instead of the deployed workspace — no deploy needed.
pipeline run <folder:string> - run a cascade: from --from (a root OR any mid-DAG model), fan downstream up to the --to end node(s)
--from <script:string> - Start script (short name or path). May be any node, including a mid-DAG model — that node plus its transitive downstream runs, upstream is NOT re-run (dbt --select model+). Defaults to the folder's sole schedule/manual root.
--to <node:string> - End node(s) to stop at — script names/paths or asset URIs (e.g. datatable://main/staged). Repeatable or comma-separated. Omit to run the full downstream.
--dry-run - Print the topological run plan without executing.
--json - Output the plan as JSON (for piping to jq).
--local - Run the local working-tree scripts via preview (no deploy) instead of the deployed versions; the graph is built from local files.
--upload <binding:string> - Bind an object to a data_upload/webhook entry point so it runs in the cascade, as SCRIPT[:PARAM]=SOURCE (SOURCE is a local file or an s3://key). Local files are uploaded to the workspace store; the S3Object param is inferred when the script has exactly one. Repeatable.
--arg <binding:string> - Pass a plain run arg to a script in the cascade, as SCRIPT:PARAM=VALUE (VALUE is parsed as JSON when possible, else taken as a string — e.g. daily_report:partition=2026-07-02). Repeatable.
--partition <value:string> - Partition value for // partitioned scripts in the run (e.g. 2026-06-30) — use it to backfill a past slice. With --local, time kinds (daily/hourly/weekly/monthly) default to the current UTC period when omitted; dynamic always needs it. Deployed runs without it defer to backend run-start resolution.
pipeline docs <folder:string> - generate PIPELINE.md (+ AGENTS.md pointer) describing a folder's pipeline graph and datatable schemas, for an editor / agentic loop
--local - Build the graph from local working-tree files instead of the deployed workspace.
pipeline dev [folder:string] - Live-preview a data pipeline from local files: watch an f/<folder> of // pipeline scripts, push the working-tree graph to the dev page, and run the cascade via preview (no deploy).
--port <port:number> - Port for the dev WebSocket server.
--no-open - Do not open the browser automatically.
--frontend <origin:string> - Origin serving the /pipeline_dev page (e.g. http://localhost:3000 for a locally-run frontend). Defaults to the workspace remote; use it when the remote's deployed frontend predates the dev page.
protection-rules
Sync workspace protection rules between protection-rules.yaml and Windmill. The file is keyed by workspace name; keys must match wmill.yaml 'workspaces'.
Subcommands:
protection-rules pull [workspace:string] - Pull protection rules from Windmill into protection-rules.yaml for a workspace
--all - Pull every workspace defined in wmill.yaml
--dry-run - Show what would change without writing the file
--json-output - Output in JSON format
protection-rules push [workspace:string] - Push protection rules from protection-rules.yaml to Windmill for a workspace (full reconcile: creates, updates, and deletes)
--all - Push every workspace defined in protection-rules.yaml
--dry-run - Show what would change without applying
--json-output - Output in JSON format
--yes - Skip the confirmation prompt (including deletions)
queues
List all queues with their metrics
Arguments: [workspace:string] the optional workspace to filter by (default to all workspaces)
Options:
--instance [instance] - Name of the instance to push to, override the active instance
--base-url [baseUrl] - If used with --token, will be used as the base url for the instance
refresh
Refresh wmill-managed project files (AGENTS.wmill.md, skills, tsconfig.wmill.json)
Subcommands:
refresh prompts - Refresh AGENTS.wmill.md and managed skills. User-owned AGENTS.md and CLAUDE.md are never overwritten unless you opt in.
--yes - Non-interactive: append the @AGENTS.wmill.md include to an existing AGENTS.md / CLAUDE.md without prompting. Without it, a non-interactive run leaves an unlinked file untouched.
refresh tsconfig - Refresh the wmill-managed tsconfig.wmill.json (and Deno import map for Deno projects)
--yes - Non-interactive: wire an existing custom tsconfig.json/deno.json to the managed file without prompting (a previously-generated config is always migrated automatically).
resource
resource related commands
Options:
--json - Output as JSON (for piping to jq)
Subcommands:
resource list - list all resources
--json - Output as JSON (for piping to jq)
resource get <path:string> - get a resource's details
--json - Output as JSON (for piping to jq)
resource new <path:string> - create a new resource locally
resource push <file_path:string> <remote_path:string> - push a local resource spec. This overrides any remote versions.
resource-type
resource type related commands
Options:
--json - Output as JSON (for piping to jq)
Subcommands:
resource-type list - list all resource types
--schema - Show schema in the output
--json - Output as JSON (for piping to jq)
resource-type get <path:string> - get a resource type's details
--json - Output as JSON (for piping to jq)
resource-type new <name:string> - create a new resource type locally
resource-type push <file_path:string> <name:string> - push a local resource spec. This overrides any remote versions.
resource-type generate-namespace - Create a TypeScript definition file with the RT namespace generated from the resource types
schedule
schedule related commands
Options:
--json - Output as JSON (for piping to jq)
Subcommands:
schedule list - list all schedules
--json - Output as JSON (for piping to jq)
schedule get <path:string> - get a schedule's details
--json - Output as JSON (for piping to jq)
schedule new <path:string> - create a new schedule locally
schedule push <file_path:string> <remote_path:string> - push a local schedule spec. This overrides any remote versions.
schedule enable <path:string> - Enable a schedule
--force - Bypass the fork-conflict warning when the parent workspace has the same schedule (acknowledges that both crons will fire)
schedule disable <path:string> - Disable a schedule
schedule set-permissioned-as <path:string> <email:string> - Set the email (run-as user) for a schedule (requires admin or wm_deployers group)
script
script related commands
Options:
--show-archived - Show archived scripts instead of active ones
--json - Output as JSON (for piping to jq)
Subcommands:
script list - list all scripts
--show-archived - Show archived scripts instead of active ones
--json - Output as JSON (for piping to jq)
script push <path:file> - push a local script spec. This overrides any remote versions. Use the script file (.ts, .js, .py, .sh)
--message <message:string> - Deployment message
script get <path:file> - get a script's details
--json - Output as JSON (for piping to jq)
script show <path:file> - show a script's content (alias for get)
script run <path:file> - run a script by path
-d --data <data:file> - 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.
--tag <tag:string> - Override the worker tag the run is dispatched to (e.g. to route it to dev workers instead of the script's default tag).
script preview <path:file> - preview a local script without deploying it. Supports both regular and codebase scripts.
-d --data <data:file> - 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 than the final output. Useful for scripting.
--tag <tag:string> - Override the worker tag the preview is dispatched to (e.g. to route it to dev workers instead of the script's default tag).
script new <path:file> <language:string> - create a new script
--summary <summary:string> - script summary
--description <description:string> - script description
script bootstrap <path:file> <language:string> - create a new script (alias for new)
--summary <summary:string> - script summary
--description <description:string> - script description
script set-permissioned-as <path:string> <email:string> - Set the on_behalf_of_email for a script (requires admin or wm_deployers group)
script history <path:string> - show version history for a script
--json - Output as JSON (for piping to jq)
sync
sync local with a remote workspaces or the opposite (push or pull)
Subcommands:
sync pull - Pull any remote changes and apply them locally.
--yes - Pull without needing confirmation
--dry-run - Show changes that would be pulled without actually pushing
--plain-secrets - Pull secrets as plain text
--json - Use JSON instead of YAML
--skip-variables - Skip syncing variables (including secrets)
--skip-secrets - Skip syncing only secrets variables
--include-secrets - Include secrets in sync (overrides skipSecrets in wmill.yaml)
--skip-resources - Skip syncing resources
--skip-resource-types - Skip syncing resource types
--skip-scripts - Skip syncing scripts
--skip-flows - Skip syncing flows
--skip-apps - Skip syncing apps
--skip-folders - Skip syncing folders
--skip-workspace-dependencies - Skip syncing workspace dependencies
--skip-scripts-metadata - Skip syncing scripts metadata, focus solely on logic
--include-schedules - Include syncing schedules
--include-triggers - Include syncing triggers
--include-users - Include syncing users
--include-groups - Include syncing groups
--include-settings - Include syncing workspace settings
--include-key - Include workspace encryption key
--keep-deleted - Do not delete local files for items that no longer exist on the remote workspace. Only adds and updates.
--skip-branch-validation - Skip git branch validation and prompts
--json-output - Output results in JSON format
-i --includes <patterns:file[]> - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Overrides wmill.yaml includes
-e --excludes <patterns:file[]> - Comma separated patterns to specify which file to NOT take into account. Overrides wmill.yaml excludes
--extra-includes <patterns:file[]> - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Useful to still take wmill.yaml into account and act as a second pattern to satisfy
--repository <repo:string> - Specify repository path (e.g., u/user/repo) when multiple repositories exist
--promotion <branch:string> - Use promotionOverrides from the specified branch instead of regular overrides
--branch, --env <branch:string> - [Deprecated: use --workspace] Override the current git branch/environment
sync push - Push any local changes and apply them remotely.
--yes - Push without needing confirmation
--dry-run - Show changes that would be pushed without actually pushing
--plain-secrets - Push secrets as plain text
--json - Use JSON instead of YAML
--skip-variables - Skip syncing variables (including secrets)
--skip-secrets - Skip syncing only secrets variables
--include-secrets - Include secrets in sync (overrides skipSecrets in wmill.yaml)
--skip-resources - Skip syncing resources
--skip-resource-types - Skip syncing resource types
--skip-scripts - Skip syncing scripts
--skip-flows - Skip syncing flows
--skip-apps - Skip syncing apps
--skip-folders - Skip syncing folders
--skip-workspace-dependencies - Skip syncing workspace dependencies
--skip-scripts-metadata - Skip syncing scripts metadata, focus solely on logic
--include-schedules - Include syncing schedules
--include-triggers - Include syncing triggers
--include-users - Include syncing users
--include-groups - Include syncing groups
--include-settings - Include syncing workspace settings
--include-key - Include workspace encryption key
--skip-reencrypt-on-key-change - When the pushed encryption key differs from the remote, do NOT re-encrypt existing remote secrets. Only safe if they are already encrypted with the new key (e.g. workspace/instance migration). Default is to re-encrypt.
--keep-deleted - Do not delete remote items that no longer exist locally. Only adds and updates.
--skip-branch-validation - Skip git branch validation and prompts
--json-output - Output results in JSON format
-i --includes <patterns:file[]> - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string)
-e --excludes <patterns:file[]> - Comma separated patterns to specify which file to NOT take into account.
--extra-includes <patterns:file[]> - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Useful to still take wmill.yaml into account and act as a second pattern to satisfy
--message <message:string> - Include a message that will be added to all scripts/flows/apps updated during this push
--parallel <number> - Number of changes to process in parallel
--repository <repo:string> - Specify repository path (e.g., u/user/repo) when multiple repositories exist
--branch, --env <branch:string> - [Deprecated: use --workspace] Override the current git branch/environment
--lint - Run lint validation before pushing
--locks-required - Fail if scripts or flow inline scripts that need locks have no locks
--auto-metadata - Automatically regenerate stale metadata (locks and schemas) before pushing
--accept-overriding-permissioned-as-with-self - Accept that items with a different permissioned_as will be updated with your own user
token
Manage API tokens
Options:
--json - Output as JSON (for piping to jq)
Subcommands:
token list - List API tokens
--json - Output as JSON (for piping to jq)
token create - Create a new API token
--label <label:string> - Token label
--expiration <expiration:string> - Token expiration (ISO 8601 timestamp)
token delete <token_prefix:string> - Delete a token by its prefix
trigger
trigger related commands
Options:
--json - Output as JSON (for piping to jq)
Subcommands:
…(truncated)
1---
2name: cli-commands
3description: MUST use when using the CLI, including debugging job failures and inspecting run history via `wmill job`.
4metadata:
5 source: https://skillmd.com/skills/windmill-labs/cli-commands
6---
7
8# Windmill CLI Commands
9
10The Windmill CLI (`wmill`) provides commands for managing scripts, flows, apps, and other resources.
11
12## Global Options
13
14- `--workspace <workspace:string>` - Specify the target workspace. This overrides the default workspace.
15- `--debug --verbose` - Show debug/verbose logs
16- `--show-diffs` - Show diff informations when syncing (may show sensitive informations)
17- `--token <token:string>` - Specify an API token. This will override any stored token.
18- `--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.
19- `--config-dir <configDir:string>` - Specify a custom config directory. Overrides WMILL_CONFIG_DIR environment variable and default ~/.config location.
20
21## Commands
22
23### app
24
25app related commands
26
27**Options:**
28- `--json` - Output as JSON (for piping to jq)
29
30**Subcommands:**
31
32- `app list` - list all apps
33 - `--json` - Output as JSON (for piping to jq)
34- `app get <path:string>` - get an app's details
35 - `--json` - Output as JSON (for piping to jq)
36- `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.
37- `app dev [app_folder:string]` - Start a development server for building apps with live reload and hot module replacement
38 - `--port <port:number>` - Port to run the dev server on (will find next available port if occupied)
39 - `--host <host:string>` - Host to bind the dev server to
40 - `--entry <entry:string>` - Entry point file (default: index.ts for Svelte/Vue, index.tsx otherwise)
41 - `--no-open` - Don't automatically open the browser
42 - `--recording` - Frame the app in a shell with a Record button, to capture a replayable session recording of the app under development
43- `app lint [app_folder:string]` - Lint a raw app folder to validate structure and buildability
44 - `--fix` - Attempt to fix common issues (not implemented yet)
45- `app bundle [app_folder:string]` - Bundle a raw app folder to js/css without deploying it
46 - `--out <dir:string>` - Directory to write bundle.js and bundle.css into (default: <app_folder>/dist)
47 - `--no-minify` - Skip minification
48- `app new` - create a new raw app from a template
49 - `--summary <summary:string>` - App summary (short description). Skips the prompt when provided. Triggers non-interactive mode.
50 - `--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.
51 - `--framework <framework:string>` - Framework template: react19 | react18 | svelte5 | vue. Skips the prompt when provided. Triggers non-interactive mode.
52 - `--datatable <datatable:string>` - Datatable to wire up. Without this flag in non-interactive mode, no datatable is configured.
53 - `--schema <schema:string>` - Schema to use with --datatable. Created (CREATE SCHEMA IF NOT EXISTS) if it doesn't already exist.
54 - `--overwrite` - Overwrite the target directory if it already exists, without prompting.
55 - `--no-open-in-desktop` - Do not prompt to open the new app in Claude Desktop.
56- `app generate-agents [app_folder:string]` - regenerate AGENTS.md and DATATABLES.md from remote workspace
57- `app set-permissioned-as <path:string> <email:string>` - Set the on_behalf_of_email for an app (requires admin or wm_deployers group)
58
59### audit
60
61View audit logs (requires admin)
62
63**Subcommands:**
64
65- `audit list` - List audit log entries
66- `audit get <id:string>` - Get a specific audit log entry
67 - `--json` - Output as JSON (for piping to jq)
68
69### config
70
71Show all available wmill.yaml configuration options
72
73**Options:**
74- `--json` - Output as JSON for programmatic consumption
75
76**Subcommands:**
77
78- `config migrate` - Migrate wmill.yaml from gitBranches/environments to workspaces format
79
80### datatable
81
82datatable related commands
83
84**Subcommands:**
85
86- `datatable list` - list all datatables in the workspace
87 - `--json` - Output as JSON (for piping to jq)
88- `datatable run <sql:string>` - run a SQL query on a datatable
89 - `-n --name <name:string>` - Datatable name (default: main)
90 - `-s --silent` - Output only the final result as JSON. Useful for scripting.
91- `datatable migrate` - manage datatable migrations
92 - `datatable migrate new <name:string>` - scaffold a new migration (.up.sql / .down.sql files)
93 - `-d --datatable <datatable:string>` - Target datatable (default: main)
94 - `datatable migrate up` - apply all pending migrations to the main datatable (or one via --datatable)
95 - `-d --datatable <datatable:string>` - Target datatable (default: main)
96 - `datatable migrate down` - roll back the most recent migration on the main datatable (or one via --datatable)
97 - `-d --datatable <datatable:string>` - Target datatable (default: main)
98- `datatable create [name:string]` - register a datatable database in the workspace (default: instance-backed 'main') so scripts can use datatable://<name>
99 - `--resource <resource:string>` - Back the datatable with an existing postgresql resource path instead of the instance database
100 - `--force` - Allow adding to a workspace that already has datatables (fork metadata on existing ones is not preserved)
101- `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
102 - `--port <port:number>` - Port to listen on (default: first free port in 5433-5500)
103 - `--host <host:string>` - Bind address (default: 127.0.0.1)
104 - `--password <password:string>` - Password for Postgres clients (default: generate a random password at startup)
105- `datatable psql` - Start a serve listener and launch psql connected to it
106 - `-n --name <name:string>` - Datatable to connect psql to (default: main)
107 - `--port <port:number>` - Port the proxy listens on (default: first free port in 5433-5500)
108 - `--host <host:string>` - Bind address for the proxy (default: 127.0.0.1)
109 - `--password <password:string>` - Password for the temporary Postgres proxy (default: generate a random password at startup)
110
111### dependencies
112
113workspace dependencies related commands
114
115**Alias:** `deps`
116
117**Subcommands:**
118
119- `dependencies push <file_path:string>` - Push workspace dependencies from a local file
120
121### dev
122
123Watch local file changes and live-reload the dev page for preview. Does NOT deploy to the remote workspace — use wmill sync push for that.
124
125**Options:**
126- `--includes <pattern...:string>` - Filter paths given a glob pattern or path
127- `--proxy-port <port:number>` - Port for a localhost reverse proxy to the remote Windmill server
128- `--path <path:string>` - Watch a specific windmill path (e.g., u/admin/my_script or f/my_flow)
129- `--no-open` - Do not open the browser automatically
130
131### docs
132
133Search Windmill documentation.
134
135**Arguments:** `<query:string>`
136
137**Options:**
138- `--json` - Output results as JSON.
139
140### ducklake
141
142ducklake related commands
143
144**Subcommands:**
145
146- `ducklake list` - list all ducklakes in the workspace
147 - `--json` - Output as JSON (for piping to jq)
148- `ducklake run <sql:string>` - run a SQL query on a ducklake
149 - `-n --name <name:string>` - Ducklake name (default: main)
150 - `-s --silent` - Output only the final result as JSON. Useful for scripting.
151
152### flow
153
154flow related commands
155
156**Options:**
157- `--show-archived` - Enable archived flows in output
158- `--json` - Output as JSON (for piping to jq)
159
160**Subcommands:**
161
162- `flow list` - list all flows
163 - `--show-archived` - Enable archived flows in output
164 - `--json` - Output as JSON (for piping to jq)
165- `flow get <path:string>` - get a flow's details
166 - `--json` - Output as JSON (for piping to jq)
167- `flow push <file_path:string> <remote_path:string>` - push a local flow spec. This overrides any remote versions.
168 - `--message <message:string>` - Deployment message
169- `flow run <path:string>` - run a flow by path.
170 - `-d --data <data:string>` - Inputs specified as a JSON string or a file using @<filename> or stdin using @-. A resource argument is the bare string $res:<path> as its whole value, and a variable argument is the bare string $var:<path> — not an object wrapper keyed on $res/$var, and not a plain path.
171 - `-s --silent` - Do not ouput anything other then the final output. Useful for scripting.
172 - `--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).
173- `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 <id> 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).
174 - `-d --data <data:string>` - Inputs specified as a JSON string or a file using @<filename> or stdin using @-. A resource argument is the bare string $res:<path> as its whole value, and a variable argument is the bare string $var:<path> — not an object wrapper keyed on $res/$var, and not a plain path.
175 - `-s --silent` - Do not output anything other then the final output. Useful for scripting.
176 - `--remote` - Use deployed workspace scripts for PathScript steps instead of local files.
177 - `--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.
178 - `--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).
179- `flow new <flow_path:string>` - create a new empty flow
180 - `--summary <summary:string>` - flow summary
181 - `--description <description:string>` - flow description
182- `flow bootstrap <flow_path:string>` - create a new empty flow (alias for new)
183 - `--summary <summary:string>` - flow summary
184 - `--description <description:string>` - flow description
185- `flow history <path:string>` - Show version history for a flow
186 - `--json` - Output as JSON (for piping to jq)
187- `flow show-version <path:string> <version:string>` - Show a specific version of a flow
188 - `--json` - Output as JSON (for piping to jq)
189- `flow set-permissioned-as <path:string> <email:string>` - Set the on_behalf_of_email for a flow (requires admin or wm_deployers group)
190
191### folder
192
193folder related commands
194
195**Options:**
196- `--json` - Output as JSON (for piping to jq)
197
198**Subcommands:**
199
200- `folder list` - list all folders
201 - `--json` - Output as JSON (for piping to jq)
202- `folder get <name:string>` - get a folder's details
203 - `--json` - Output as JSON (for piping to jq)
204- `folder new <name:string>` - create a new folder locally
205 - `--summary <summary:string>` - folder summary
206- `folder push <name:string>` - push a local folder to the remote by name. This overrides any remote versions.
207- `folder add-missing` - create default folder.meta.yaml for all subdirectories of f/ that are missing one
208 - `-y, --yes` - skip confirmation prompt
209- `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.
210 - `--test-path <path:string>` - Test which rule matches this item path (e.g. f/prod/jobs/my_script)
211 - `--json` - Output as JSON
212
213### generate-metadata
214
215Regenerate 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.
216
217**Arguments:** `[folder:string]`
218
219**Options:**
220- `--yes` - Skip confirmation prompt
221- `--dry-run` - Show what would be updated without making changes
222- `--lock-only` - Re-generate only the lock files
223- `--schema-only` - Re-generate only script schemas (skips flows and apps)
224- `--skip-scripts` - Skip processing scripts
225- `--skip-flows` - Skip processing flows
226- `--skip-apps` - Skip processing apps
227- `--strict-folder-boundaries` - Only update items inside the specified folder (requires folder argument)
228- `--parallel <n:number>` - Number of items to process in parallel
229- `-i --includes <patterns:file[]>` - Comma separated patterns to specify which files to include
230- `-e --excludes <patterns:file[]>` - Comma separated patterns to specify which files to exclude
231
232**Subcommands:**
233
234- `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.
235 - `--skip-scripts` - Skip processing scripts
236 - `--skip-flows` - Skip processing flows
237 - `--skip-apps` - Skip processing apps
238 - `--parallel <n:number>` - Number of items to process in parallel
239 - `-i --includes <patterns:file[]>` - Comma separated patterns to specify which files to include
240 - `-e --excludes <patterns:file[]>` - Comma separated patterns to specify which files to exclude
241
242### gitsync-settings
243
244Manage git-sync settings between local wmill.yaml and Windmill backend
245
246**Subcommands:**
247
248- `gitsync-settings pull` - Pull git-sync settings from Windmill backend to local wmill.yaml
249 - `--repository <repo:string>` - Specify repository path (e.g., u/user/repo)
250 - `--default` - Write settings to top-level defaults instead of overrides
251 - `--replace` - Replace existing settings (non-interactive mode)
252 - `--override` - Add branch-specific override (non-interactive mode)
253 - `--diff` - Show differences without applying changes
254 - `--json-output` - Output in JSON format
255 - `--with-backend-settings <json:string>` - Use provided JSON settings instead of querying backend (for testing)
256 - `--yes` - Skip interactive prompts and use default behavior
257 - `--promotion <branch:string>` - Use promotionOverrides from the specified branch instead of regular overrides
258- `gitsync-settings push` - Push git-sync settings from local wmill.yaml to Windmill backend
259 - `--repository <repo:string>` - Specify repository path (e.g., u/user/repo)
260 - `--diff` - Show what would be pushed without applying changes
261 - `--json-output` - Output in JSON format
262 - `--with-backend-settings <json:string>` - Use provided JSON settings instead of querying backend (for testing)
263 - `--yes` - Skip interactive prompts and use default behavior
264 - `--promotion <branch:string>` - Use promotionOverrides from the specified branch instead of regular overrides
265- `gitsync-settings status` - Report how local changes deploy to the workspace (git push vs wmill sync push)
266 - `--json-output` - Output in JSON format
267
268### group
269
270Manage workspace groups
271
272**Options:**
273- `--json` - Output as JSON (for piping to jq)
274
275**Subcommands:**
276
277- `group list` - List all groups in the workspace
278 - `--json` - Output as JSON (for piping to jq)
279- `group get <name:string>` - Get group details and members
280 - `--json` - Output as JSON (for piping to jq)
281- `group create <name:string>` - Create a new group
282 - `--summary <summary:string>` - Group summary/description
283- `group delete <name:string>` - Delete a group
284- `group add-user <name:string> <username:string>` - Add a user to a group
285- `group remove-user <name:string> <username:string>` - Remove a user from a group
286
287### hub
288
289Hub related commands. EXPERIMENTAL. INTERNAL USE ONLY.
290
291**Subcommands:**
292
293- `hub pull` - pull any supported definitions. EXPERIMENTAL.
294
295### init
296
297Bootstrap a windmill project with a wmill.yaml file
298
299**Options:**
300- `--use-default` - Use default settings without checking backend
301- `--use-backend` - Use backend git-sync settings if available
302- `--repository <repo:string>` - Specify repository path (e.g., u/user/repo) when using backend settings
303- `--bind-profile` - Automatically bind active workspace profile to current Git branch
304- `--no-bind-profile` - Skip workspace profile binding prompt
305
306### instance
307
308sync local with a remote instance or the opposite (push or pull)
309
310**Subcommands:**
311
312- `instance add [instance_name:string] [remote:string] [token:string]` - Add a new instance
313- `instance remove <instance:string:instance>` - Remove an instance
314- `instance switch <instance:string:instance>` - Switch the current instance
315- `instance pull` - Pull instance settings, users, configs, instance groups and overwrite local
316 - `--yes` - Pull without needing confirmation
317 - `--dry-run` - Perform a dry run without making changes
318 - `--skip-users` - Skip pulling users
319 - `--skip-settings` - Skip pulling settings
320 - `--skip-configs` - Skip pulling configs (worker groups)
321 - `--skip-groups` - Skip pulling instance groups
322 - `--include-workspaces` - Also pull workspaces
323 - `--folder-per-instance` - Create a folder per instance
324 - `--instance <instance:string>` - Name of the instance to pull from, override the active instance
325 - `--prefix <prefix:string>` - Prefix of the local workspaces to pull, used to create the folders when using --include-workspaces
326 - `--prefix-settings` - Store instance yamls inside prefixed folders when using --prefix and --folder-per-instance
327- `instance push` - Push instance settings, users, configs, group and overwrite remote
328 - `--yes` - Push without needing confirmation
329 - `--dry-run` - Perform a dry run without making changes
330 - `--skip-users` - Skip pushing users
331 - `--skip-settings` - Skip pushing settings
332 - `--skip-configs` - Skip pushing configs (worker groups)
333 - `--skip-groups` - Skip pushing instance groups
334 - `--include-workspaces` - Also push workspaces
335 - `--folder-per-instance` - Create a folder per instance
336 - `--instance <instance:string>` - Name of the instance to push to, override the active instance
337 - `--prefix <prefix:string>` - Prefix of the local workspaces folders to push
338 - `--prefix-settings` - Store instance yamls inside prefixed folders when using --prefix and --folder-per-instance
339- `instance whoami` - Display information about the currently logged-in user
340- `instance get-config` - Dump the current instance config (global settings + worker configs) as YAML
341 - `-o, --output-file <file:string>` - Write YAML to a file instead of stdout
342 - `--show-secrets` - Include sensitive fields (license key, JWT secret) without prompting
343 - `--instance <instance:string>` - Name of the instance, override the active instance
344- `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.
345 - `--bot-token <bot_token:string>` - Slack bot token (xoxb-...)
346 - `--team-id <team_id:string>` - Slack team id
347 - `--team-name <team_name:string>` - Slack team name
348 - `--instance <instance:string>` - Instance profile to connect against (defaults to the active instance)
349
350### job
351
352Manage jobs (list, inspect, cancel)
353
354**Subcommands:**
355
356- `job list` - List recent jobs
357- `job get <id:string>` - Get job details. For flows: shows step tree with sub-job IDs
358 - `--json` - Output as JSON (for piping to jq)
359- `job result <id:string>` - Get the result of a completed job (machine-friendly)
360- `job logs <id:string>` - Get job logs. For flows: aggregates all step logs
361- `job cancel <id:string>` - Cancel a running or queued job
362 - `--reason <reason:string>` - Reason for cancellation
363- `job rerun <id:string>` - Re-run a completed job with the same args. Prints the new job UUID on stdout.
364- `job restart <id:string>` - Restart a completed flow at a given top-level step. Prints the new flow job UUID on stdout.
365 - `--step <stepId:string>` - Top-level step id to restart the flow from
366 - `--iteration <n:number>` - For a top-level branchall or for-loop step, the iteration to restart at
367
368### jobs
369
370Manage jobs (import/export)
371
372**Subcommands:**
373
374- `jobs pull [workspace:string]` - Pull completed and queued jobs from workspace
375 - `-c, --completed-output <file:string>` - Completed jobs output file (default: completed_jobs.json)
376 - `-q, --queued-output <file:string>` - Queued jobs output file (default: queued_jobs.json)
377 - `--skip-worker-check` - Skip checking for active workers before export
378- `jobs push [workspace:string]` - Push completed and queued jobs to workspace
379 - `-c, --completed-file <file:string>` - Completed jobs input file (default: completed_jobs.json)
380 - `-q, --queued-file <file:string>` - Queued jobs input file (default: queued_jobs.json)
381 - `--skip-worker-check` - Skip checking for active workers before import
382
383### lint
384
385Validate Windmill flow, schedule, and trigger YAML files in a directory
386
387**Arguments:** `[directory:string]`
388
389**Options:**
390- `--json` - Output results in JSON format
391- `--fail-on-warn` - Exit with code 1 when warnings are emitted
392- `--locks-required` - Fail if scripts or flow inline scripts that need locks have no locks
393- `-w, --watch` - Watch for file changes and re-lint automatically
394
395### object-storage
396
397Object storage (S3) related commands. Operates on the workspace's default object storage; use --storage to target a configured secondary storage.
398
399**Alias:** `s3`
400
401**Subcommands:**
402
403- `object-storage list` - List configured object storages for the workspace (default + secondary).
404 - `--json` - Output as JSON (for piping to jq)
405- `object-storage files [prefix:string]` - List files in an object storage. Optionally filter by prefix.
406 - `--json` - Output as JSON (for piping to jq)
407 - `--max-keys <maxKeys:number>` - Page size (default 100)
408 - `--marker <marker:string>` - Pagination marker from a previous response
409 - `--storage <storage:string>` - Secondary storage name (omit for the workspace default)
410- `object-storage upload <local_path:string> <file_key:string>` - Upload a local file to object storage at the given file key.
411 - `--storage <storage:string>` - Secondary storage name
412 - `--content-type <contentType:string>` - Content-Type header to set on the object
413 - `--content-disposition <contentDisposition:string>` - Content-Disposition header to set on the object
414- `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.
415 - `--storage <storage:string>` - Secondary storage name
416 - `--stdout` - Write file contents to stdout instead of a file
417- `object-storage delete <file_key:string>` - Delete an object from object storage. Prompts for confirmation unless --yes is set.
418 - `--storage <storage:string>` - Secondary storage name
419 - `--yes` - Skip the confirmation prompt
420- `object-storage move <src_file_key:string> <dest_file_key:string>` - Move an object within the same storage (rename or relocate by key).
421 - `--storage <storage:string>` - Secondary storage name
422- `object-storage info <file_key:string>` - Show metadata (size, mime, last-modified) for an object.
423 - `--json` - Output as JSON (for piping to jq)
424 - `--storage <storage:string>` - Secondary storage name
425- `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.
426 - `--storage <storage:string>` - Secondary storage name
427 - `--mime <mime:string>` - Override the detected mime type (e.g. text/csv)
428 - `--bytes-from <bytesFrom:number>` - Start offset in bytes
429 - `--bytes-length <bytesLength:number>` - Number of bytes to read
430 - `--csv-separator <csvSeparator:string>` - CSV column separator (default ,)
431 - `--csv-header` - Treat the first CSV row as a header
432
433### pipeline
434
435inspect asset-driven pipelines (scripts marked `// pipeline`, wired by `// on <spec>` annotations)
436
437**Subcommands:**
438
439- `pipeline list` - list pipeline folders in the workspace
440 - `--json` - Output as JSON (for piping to jq)
441- `pipeline show <folder:string>` - render a pipeline folder's DAG (sources, lineage, subscriptions) in the terminal
442 - `--json` - Output the raw asset graph as JSON
443 - `--local` - Build the graph from local working-tree files (// pipeline scripts) instead of the deployed workspace — no deploy needed.
444- `pipeline run <folder:string>` - run a cascade: from --from (a root OR any mid-DAG model), fan downstream up to the --to end node(s)
445 - `--from <script:string>` - Start script (short name or path). May be any node, including a mid-DAG model — that node plus its transitive downstream runs, upstream is NOT re-run (dbt `--select model+`). Defaults to the folder's sole schedule/manual root.
446 - `--to <node:string>` - End node(s) to stop at — script names/paths or asset URIs (e.g. datatable://main/staged). Repeatable or comma-separated. Omit to run the full downstream.
447 - `--dry-run` - Print the topological run plan without executing.
448 - `--json` - Output the plan as JSON (for piping to jq).
449 - `--local` - Run the local working-tree scripts via preview (no deploy) instead of the deployed versions; the graph is built from local files.
450 - `--upload <binding:string>` - Bind an object to a data_upload/webhook entry point so it runs in the cascade, as SCRIPT[:PARAM]=SOURCE (SOURCE is a local file or an s3://key). Local files are uploaded to the workspace store; the S3Object param is inferred when the script has exactly one. Repeatable.
451 - `--arg <binding:string>` - Pass a plain run arg to a script in the cascade, as SCRIPT:PARAM=VALUE (VALUE is parsed as JSON when possible, else taken as a string — e.g. daily_report:partition=2026-07-02). Repeatable.
452 - `--partition <value:string>` - Partition value for `// partitioned` scripts in the run (e.g. 2026-06-30) — use it to backfill a past slice. With --local, time kinds (daily/hourly/weekly/monthly) default to the current UTC period when omitted; `dynamic` always needs it. Deployed runs without it defer to backend run-start resolution.
453- `pipeline docs <folder:string>` - generate PIPELINE.md (+ AGENTS.md pointer) describing a folder's pipeline graph and datatable schemas, for an editor / agentic loop
454 - `--local` - Build the graph from local working-tree files instead of the deployed workspace.
455- `pipeline dev [folder:string]` - Live-preview a data pipeline from local files: watch an `f/<folder>` of `// pipeline` scripts, push the working-tree graph to the dev page, and run the cascade via preview (no deploy).
456 - `--port <port:number>` - Port for the dev WebSocket server.
457 - `--no-open` - Do not open the browser automatically.
458 - `--frontend <origin:string>` - Origin serving the /pipeline_dev page (e.g. http://localhost:3000 for a locally-run frontend). Defaults to the workspace remote; use it when the remote's deployed frontend predates the dev page.
459
460### protection-rules
461
462Sync workspace protection rules between protection-rules.yaml and Windmill. The file is keyed by workspace name; keys must match wmill.yaml 'workspaces'.
463
464**Subcommands:**
465
466- `protection-rules pull [workspace:string]` - Pull protection rules from Windmill into protection-rules.yaml for a workspace
467 - `--all` - Pull every workspace defined in wmill.yaml
468 - `--dry-run` - Show what would change without writing the file
469 - `--json-output` - Output in JSON format
470- `protection-rules push [workspace:string]` - Push protection rules from protection-rules.yaml to Windmill for a workspace (full reconcile: creates, updates, and deletes)
471 - `--all` - Push every workspace defined in protection-rules.yaml
472 - `--dry-run` - Show what would change without applying
473 - `--json-output` - Output in JSON format
474 - `--yes` - Skip the confirmation prompt (including deletions)
475
476### queues
477
478List all queues with their metrics
479
480**Arguments:** `[workspace:string] the optional workspace to filter by (default to all workspaces)`
481
482**Options:**
483- `--instance [instance]` - Name of the instance to push to, override the active instance
484- `--base-url [baseUrl]` - If used with --token, will be used as the base url for the instance
485
486### refresh
487
488Refresh wmill-managed project files (AGENTS.wmill.md, skills, tsconfig.wmill.json)
489
490**Subcommands:**
491
492- `refresh prompts` - Refresh AGENTS.wmill.md and managed skills. User-owned AGENTS.md and CLAUDE.md are never overwritten unless you opt in.
493 - `--yes` - Non-interactive: append the @AGENTS.wmill.md include to an existing AGENTS.md / CLAUDE.md without prompting. Without it, a non-interactive run leaves an unlinked file untouched.
494- `refresh tsconfig` - Refresh the wmill-managed tsconfig.wmill.json (and Deno import map for Deno projects)
495 - `--yes` - Non-interactive: wire an existing custom tsconfig.json/deno.json to the managed file without prompting (a previously-generated config is always migrated automatically).
496
497### resource
498
499resource related commands
500
501**Options:**
502- `--json` - Output as JSON (for piping to jq)
503
504**Subcommands:**
505
506- `resource list` - list all resources
507 - `--json` - Output as JSON (for piping to jq)
508- `resource get <path:string>` - get a resource's details
509 - `--json` - Output as JSON (for piping to jq)
510- `resource new <path:string>` - create a new resource locally
511- `resource push <file_path:string> <remote_path:string>` - push a local resource spec. This overrides any remote versions.
512
513### resource-type
514
515resource type related commands
516
517**Options:**
518- `--json` - Output as JSON (for piping to jq)
519
520**Subcommands:**
521
522- `resource-type list` - list all resource types
523 - `--schema` - Show schema in the output
524 - `--json` - Output as JSON (for piping to jq)
525- `resource-type get <path:string>` - get a resource type's details
526 - `--json` - Output as JSON (for piping to jq)
527- `resource-type new <name:string>` - create a new resource type locally
528- `resource-type push <file_path:string> <name:string>` - push a local resource spec. This overrides any remote versions.
529- `resource-type generate-namespace` - Create a TypeScript definition file with the RT namespace generated from the resource types
530
531### schedule
532
533schedule related commands
534
535**Options:**
536- `--json` - Output as JSON (for piping to jq)
537
538**Subcommands:**
539
540- `schedule list` - list all schedules
541 - `--json` - Output as JSON (for piping to jq)
542- `schedule get <path:string>` - get a schedule's details
543 - `--json` - Output as JSON (for piping to jq)
544- `schedule new <path:string>` - create a new schedule locally
545- `schedule push <file_path:string> <remote_path:string>` - push a local schedule spec. This overrides any remote versions.
546- `schedule enable <path:string>` - Enable a schedule
547 - `--force` - Bypass the fork-conflict warning when the parent workspace has the same schedule (acknowledges that both crons will fire)
548- `schedule disable <path:string>` - Disable a schedule
549- `schedule set-permissioned-as <path:string> <email:string>` - Set the email (run-as user) for a schedule (requires admin or wm_deployers group)
550
551### script
552
553script related commands
554
555**Options:**
556- `--show-archived` - Show archived scripts instead of active ones
557- `--json` - Output as JSON (for piping to jq)
558
559**Subcommands:**
560
561- `script list` - list all scripts
562 - `--show-archived` - Show archived scripts instead of active ones
563 - `--json` - Output as JSON (for piping to jq)
564- `script push <path:file>` - push a local script spec. This overrides any remote versions. Use the script file (.ts, .js, .py, .sh)
565 - `--message <message:string>` - Deployment message
566- `script get <path:file>` - get a script's details
567 - `--json` - Output as JSON (for piping to jq)
568- `script show <path:file>` - show a script's content (alias for get)
569- `script run <path:file>` - run a script by path
570 - `-d --data <data:file>` - Inputs specified as a JSON string or a file using @<filename> or stdin using @-. A resource argument is the bare string $res:<path> as its whole value, and a variable argument is the bare string $var:<path> — not an object wrapper keyed on $res/$var, and not a plain path.
571 - `-s --silent` - Do not output anything other then the final output. Useful for scripting.
572 - `--tag <tag:string>` - Override the worker tag the run is dispatched to (e.g. to route it to dev workers instead of the script's default tag).
573- `script preview <path:file>` - preview a local script without deploying it. Supports both regular and codebase scripts.
574 - `-d --data <data:file>` - Inputs specified as a JSON string or a file using @<filename> or stdin using @-. A resource argument is the bare string $res:<path> as its whole value, and a variable argument is the bare string $var:<path> — not an object wrapper keyed on $res/$var, and not a plain path.
575 - `-s --silent` - Do not output anything other than the final output. Useful for scripting.
576 - `--tag <tag:string>` - Override the worker tag the preview is dispatched to (e.g. to route it to dev workers instead of the script's default tag).
577- `script new <path:file> <language:string>` - create a new script
578 - `--summary <summary:string>` - script summary
579 - `--description <description:string>` - script description
580- `script bootstrap <path:file> <language:string>` - create a new script (alias for new)
581 - `--summary <summary:string>` - script summary
582 - `--description <description:string>` - script description
583- `script set-permissioned-as <path:string> <email:string>` - Set the on_behalf_of_email for a script (requires admin or wm_deployers group)
584- `script history <path:string>` - show version history for a script
585 - `--json` - Output as JSON (for piping to jq)
586
587### sync
588
589sync local with a remote workspaces or the opposite (push or pull)
590
591**Subcommands:**
592
593- `sync pull` - Pull any remote changes and apply them locally.
594 - `--yes` - Pull without needing confirmation
595 - `--dry-run` - Show changes that would be pulled without actually pushing
596 - `--plain-secrets` - Pull secrets as plain text
597 - `--json` - Use JSON instead of YAML
598 - `--skip-variables` - Skip syncing variables (including secrets)
599 - `--skip-secrets` - Skip syncing only secrets variables
600 - `--include-secrets` - Include secrets in sync (overrides skipSecrets in wmill.yaml)
601 - `--skip-resources` - Skip syncing resources
602 - `--skip-resource-types` - Skip syncing resource types
603 - `--skip-scripts` - Skip syncing scripts
604 - `--skip-flows` - Skip syncing flows
605 - `--skip-apps` - Skip syncing apps
606 - `--skip-folders` - Skip syncing folders
607 - `--skip-workspace-dependencies` - Skip syncing workspace dependencies
608 - `--skip-scripts-metadata` - Skip syncing scripts metadata, focus solely on logic
609 - `--include-schedules` - Include syncing schedules
610 - `--include-triggers` - Include syncing triggers
611 - `--include-users` - Include syncing users
612 - `--include-groups` - Include syncing groups
613 - `--include-settings` - Include syncing workspace settings
614 - `--include-key` - Include workspace encryption key
615 - `--keep-deleted` - Do not delete local files for items that no longer exist on the remote workspace. Only adds and updates.
616 - `--skip-branch-validation` - Skip git branch validation and prompts
617 - `--json-output` - Output results in JSON format
618 - `-i --includes <patterns:file[]>` - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Overrides wmill.yaml includes
619 - `-e --excludes <patterns:file[]>` - Comma separated patterns to specify which file to NOT take into account. Overrides wmill.yaml excludes
620 - `--extra-includes <patterns:file[]>` - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Useful to still take wmill.yaml into account and act as a second pattern to satisfy
621 - `--repository <repo:string>` - Specify repository path (e.g., u/user/repo) when multiple repositories exist
622 - `--promotion <branch:string>` - Use promotionOverrides from the specified branch instead of regular overrides
623 - `--branch, --env <branch:string>` - [Deprecated: use --workspace] Override the current git branch/environment
624- `sync push` - Push any local changes and apply them remotely.
625 - `--yes` - Push without needing confirmation
626 - `--dry-run` - Show changes that would be pushed without actually pushing
627 - `--plain-secrets` - Push secrets as plain text
628 - `--json` - Use JSON instead of YAML
629 - `--skip-variables` - Skip syncing variables (including secrets)
630 - `--skip-secrets` - Skip syncing only secrets variables
631 - `--include-secrets` - Include secrets in sync (overrides skipSecrets in wmill.yaml)
632 - `--skip-resources` - Skip syncing resources
633 - `--skip-resource-types` - Skip syncing resource types
634 - `--skip-scripts` - Skip syncing scripts
635 - `--skip-flows` - Skip syncing flows
636 - `--skip-apps` - Skip syncing apps
637 - `--skip-folders` - Skip syncing folders
638 - `--skip-workspace-dependencies` - Skip syncing workspace dependencies
639 - `--skip-scripts-metadata` - Skip syncing scripts metadata, focus solely on logic
640 - `--include-schedules` - Include syncing schedules
641 - `--include-triggers` - Include syncing triggers
642 - `--include-users` - Include syncing users
643 - `--include-groups` - Include syncing groups
644 - `--include-settings` - Include syncing workspace settings
645 - `--include-key` - Include workspace encryption key
646 - `--skip-reencrypt-on-key-change` - When the pushed encryption key differs from the remote, do NOT re-encrypt existing remote secrets. Only safe if they are already encrypted with the new key (e.g. workspace/instance migration). Default is to re-encrypt.
647 - `--keep-deleted` - Do not delete remote items that no longer exist locally. Only adds and updates.
648 - `--skip-branch-validation` - Skip git branch validation and prompts
649 - `--json-output` - Output results in JSON format
650 - `-i --includes <patterns:file[]>` - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string)
651 - `-e --excludes <patterns:file[]>` - Comma separated patterns to specify which file to NOT take into account.
652 - `--extra-includes <patterns:file[]>` - Comma separated patterns to specify which file to take into account (among files that are compatible with windmill). Patterns can include * (any string until '/') and ** (any string). Useful to still take wmill.yaml into account and act as a second pattern to satisfy
653 - `--message <message:string>` - Include a message that will be added to all scripts/flows/apps updated during this push
654 - `--parallel <number>` - Number of changes to process in parallel
655 - `--repository <repo:string>` - Specify repository path (e.g., u/user/repo) when multiple repositories exist
656 - `--branch, --env <branch:string>` - [Deprecated: use --workspace] Override the current git branch/environment
657 - `--lint` - Run lint validation before pushing
658 - `--locks-required` - Fail if scripts or flow inline scripts that need locks have no locks
659 - `--auto-metadata` - Automatically regenerate stale metadata (locks and schemas) before pushing
660 - `--accept-overriding-permissioned-as-with-self` - Accept that items with a different permissioned_as will be updated with your own user
661
662### token
663
664Manage API tokens
665
666**Options:**
667- `--json` - Output as JSON (for piping to jq)
668
669**Subcommands:**
670
671- `token list` - List API tokens
672 - `--json` - Output as JSON (for piping to jq)
673- `token create` - Create a new API token
674 - `--label <label:string>` - Token label
675 - `--expiration <expiration:string>` - Token expiration (ISO 8601 timestamp)
676- `token delete <token_prefix:string>` - Delete a token by its prefix
677
678### trigger
679
680trigger related commands
681
682**Options:**
683- `--json` - Output as JSON (for piping to jq)
684
685**Subcommands:**
686
687- `trigger list` - list all triggers
688 - `--json` - Output as JSON (for piping to jq)
689- `trigger get <path:string>` - get a trigger's details
690 - `--json` - Output as JSON (for piping to jq)
691 - `--kind <kind:string>` - Trigger kind (http, websocket, kafka, nats, postgres, mqtt, amqp, sqs, gcp, azure, email). Recommended for faster lookup
692- `trigger new <path:string>` - create a new trigger locally
693 - `--kind <kind:string>` - Trigger kind (required: http, websocket, kafka, nats, postgres, mqtt, amqp, sqs, gcp, azure, email)
694- `trigger push <file_path:string> <remote_path:string>` - push a local trigger spec. This overrides any remote versions.
695- `trigger set-permissioned-as <path:string> <email:string>` - Set the email (run-as user) for a trigger (requires admin or wm_deployers group)
696 - `--kind <kind:string>` - Trigger kind (required: http, websocket, kafka, nats, postgres, mqtt, amqp, sqs, gcp, azure, email)
697
698### user
699
700user related commands
701
702**Subcommands:**
703
704- `user add <email:string> [password:string]` - Create a user
705 - `--superadmin` - Specify to make the new user superadmin.
706 - `--company <company:string>` - Specify to set the company of the new user.
707 - `--name <name:string>` - Specify to set the name of the new user.
708- `user remove <email:string>` - Delete a user
709- `user create-token` - Create a new API token for the authenticated user
710 - `--email <email:string>` - Specify credentials to use for authentication. This will not be stored. It will only be used to exchange for a token with the API server, which will not be stored either.
711 - `--password <password:string>` - Specify credentials to use for authentication. This will not be stored. It will only be used to exchange for a token with the API server, which will not be stored either.
712
713### variable
714
715variable related commands
716
717**Options:**
718- `--json` - Output as JSON (for piping to jq)
719
720**Subcommands:**
721
722- `variable list` - list all variables
723 - `--json` - Output as JSON (for piping to jq)
724- `variable get <path:string>` - get a variable's details
725 - `--json` - Output as JSON (for piping to jq)
726- `variable new <path:string>` - create a new variable locally
727- `variable push <file_path:string> <remote_path:string>` - Push a local variable spec. This overrides any remote versions.
728 - `--plain-secrets` - Push secrets as plain text
729- `variable add <value:string> <remote_path:string>` - Create a new variable on the remote. This will update the variable if it already exists.
730 - `--yes` - Skip confirmation prompt when updating an existing variable
731 - `--secret` - Mark the variable as secret (default when creating a new variable)
732 - `--no-secret` - Mark the variable as non-secret (when updating, the existing setting is preserved if neither --secret nor --no-secret is passed)
733 - `--description <description:string>` - Set the variable description (when updating, the existing description is preserved if not passed)
734 - `--plain-secrets` - Push secrets as plain text
735 - `--public` - Legacy option, use --no-secret instead
736
737### version
738
739Show version information
740
741### worker-groups
742
743display worker groups, pull and push worker groups configs
744
745**Subcommands:**
746
747- `worker-groups pull` - Pull worker groups (similar to `wmill instance pull --skip-users --skip-settings --skip-groups`)
748 - `--instance` - Name of the instance to push to, override the active instance
749 - `--base-url` - Base url to be passed to the instance settings instead of the local one
750 - `--yes` - Pull without needing confirmation
751- `worker-groups push` - Push worker groups (similar to `wmill instance push --skip-users --skip-settings --skip-groups`)
752 - `--instance [instance]` - Name of the instance to push to, override the active instance
753 - `--base-url [baseUrl]` - If used with --token, will be used as the base url for the instance
754 - `--yes` - Push without needing confirmation
755
756### workers
757
758List all workers grouped by worker groups
759
760**Options:**
761- `--instance [instance]` - Name of the instance to push to, override the active instance
762- `--base-url [baseUrl]` - If used with --token, will be used as the base url for the instance
763
764### workspace
765
766workspace related commands
767
768**Alias:** `profile`
769
770**Subcommands:**
771
772- `workspace switch <workspace_name:string:workspace>` - Switch to another workspace
773- `workspace add [workspace_name:string] [workspace_id:string] [remote:string]` - Add a workspace
774 - `-c --create` - Create the workspace if it does not exist
775 - `--create-workspace-name <workspace_name:string>` - Specify the workspace name. Ignored if --create is not specified or the workspace already exists. Will default to the workspace id.
776 - `--create-username <username:string>` - Specify your own username in the newly created workspace. Ignored if --create is not specified, the workspace already exists or automatic username creation is enabled on the instance.
777- `workspace remove <workspace_name:string>` - Remove a workspace
778- `workspace whoami` - Show the currently active user
779- `workspace list` - List local workspace profiles
780- `workspace list-remote` - List workspaces on the remote server that you have access to
781 - `--as-superadmin` - List ALL workspaces on the instance (requires the token to belong to a superadmin/devops user)
782- `workspace list-forks` - List forked workspaces on the remote server
783- `workspace bind` - Create or update a workspace entry in wmill.yaml from the active profile
784 - `--workspace <name:string>` - Workspace name (default: current branch or workspaceId)
785 - `--branch <branch:string>` - Git branch to associate (default: workspace name)
786- `workspace unbind` - Remove baseUrl and workspaceId from a workspace entry
787 - `--workspace <name:string>` - Workspace to unbind
788- `workspace fork [workspace_name:string] [workspace_id:string]` - Create a forked workspace from its parent workspace.
789
790The parent is resolved from your current git branch, not from the active profile: run this from a git repo checked out on the branch mapped to the parent workspace in wmill.yaml's `workspaces:` section (a fork branch of it resolves to the same parent). `wmill workspace switch` does not change which workspace is forked.
791
792Arguments (omit both to be prompted interactively):
793 [workspace_name] Friendly display name for the fork, shown in the UI. May contain spaces, so quote it in the shell (e.g. "My Fork"). Max 50 chars. Defaults to "<parent workspace name>'s fork".
794 [workspace_id] Id for the fork. Must be a slug (no spaces or special characters) and is automatically prefixed with `wm-fork-`, so pass just the bare slug (e.g. `my-fork` becomes `wm-fork-my-fork`). This id also determines the fork's git branch name. Defaults to a slug derived from the name — or, when you are converting an existing branch into the fork branch, from that branch.
795 - `--create-workspace-name <workspace_name:string>` - Specify the workspace name. Ignored if --create is not specified or the workspace already exists. Will default to the workspace id.
796 - `--color <color:string>` - Workspace color (hex code, e.g. #ff0000)
797 - `--datatable-behavior <behavior:string>` - How to handle datatables: skip, schema_only, or schema_and_data (default: interactive prompt)
798 - `--from-branch <branch:string>` - Non-interactive override for the 'turn my current working branch into the fork' workflow: base the fork on <branch> (its bound workspace is the parent) and rename the current branch onto wm-fork/<branch>/<id>. Usually unneeded — from a working branch `wmill workspace fork` offers this interactively; from a base branch it creates a fresh fork branch.
799 - `-y --yes` - Skip interactive prompts (defaults datatable behavior to 'skip'). On a non-base branch, requires --from-branch since the base branch can't be prompted for.
800- `workspace delete-fork <fork_name:string>` - Delete a forked workspace
801 - `-y --yes` - Skip confirmation prompt
802- `workspace merge` - Compare and deploy changes between a fork and its parent workspace
803 - `--direction <direction:string>` - Deploy direction: to-parent or to-fork
804 - `--all` - Deploy all changed items including conflicts
805 - `--skip-conflicts` - Skip items modified in both workspaces
806 - `--include <items:string>` - Comma-separated kind:path items to include (e.g. script:f/test/main,flow:f/my/flow)
807 - `--exclude <items:string>` - Comma-separated kind:path items to exclude
808 - `--preserve-on-behalf-of` - Preserve original on_behalf_of/permissioned_as values
809 - `-y --yes` - Non-interactive mode (deploy without prompts)
810- `workspace connect-slack` - Non-interactively connect Slack to the active workspace using a pre-minted bot token (xoxb-...). Produces the same artifacts as the UI OAuth flow: workspace_settings fields, g/slack group, f/slack_bot folder, and the encrypted bot token variable + resource at f/slack_bot/bot_token.
811 - `--bot-token <bot_token:string>` - Slack bot token (xoxb-...)
812 - `--team-id <team_id:string>` - Slack team id
813 - `--team-name <team_name:string>` - Slack team name
814- `workspace disconnect-slack` - Clear slack_team_id / slack_name on the active workspace (marks the workspace as disconnected). Does NOT remove the bot token variable/resource/folder/group — delete those from the local sync folder and run 'wmill sync push' to tear them down. Does NOT remove the workspace-level OAuth override — set slack_oauth_client_id/_secret to '' in settings.yaml and push.
815
816
817
818# Object Storage CLI
819
820`wmill object-storage` (alias `wmill s3`) exposes the workspace's object storage (S3-compatible: AWS S3, MinIO, GCS, R2, Azure Blob) over the per-workspace `/job_helpers/*` endpoints.
821
822## Key concepts (not obvious from per-command --help)
823
824- **`file_key` is the path inside the bucket** (e.g. `reports/2026-05/orders.csv`), not a Windmill path. Do NOT pass `u/...` or `f/...` here — those are Windmill paths to scripts/flows/resources, unrelated to objects in the bucket.
825- **Scope is the active workspace.** Object storage is configured per-workspace (default storage + optional secondary storages). Switching workspaces switches which bucket the commands target.
826- **`--storage <name>` targets a secondary storage** configured on the workspace. Omit it to use the workspace's default object storage. Use `wmill object-storage list` to discover configured storages.
827- **`preview` vs `download`**: `preview` returns a peek (CSV first rows, text content, or a byte slice via `--bytes-from`/`--bytes-length`) without writing to disk. Use `download` when you want the full file on disk.
828
829## Choosing a subcommand
830
831- Look at what's there: `wmill object-storage files [prefix]` (alias `ls`) — paginated, use `--marker` to continue.
832- Inspect one file: `wmill object-storage info <file_key>` for size/mime/last-modified, `wmill object-storage preview <file_key>` for content peek.
833- Move data in: `wmill object-storage upload <local_path> <file_key>` — set `--content-type` if the receiver cares (e.g. `text/csv`).
834- Move data out: `wmill object-storage download <file_key> [output_path]` — `--stdout` to pipe.
835- Reorganize: `wmill object-storage move <src> <dest>` (same storage), `wmill object-storage delete <file_key>` (interactive confirm unless `--yes`).