{"id":17405,"library":"windmill-cli","title":"Windmill CLI","description":"The Windmill CLI (`wmill`) is a command-line interface tool designed for direct interaction with Windmill instances, an open-source platform for building and running workflows and internal tools. It provides comprehensive capabilities for managing Windmill workspaces, including adding and switching between them, and syncing resources like scripts and flows. Developers can use `wmill` to run scripts and flows, passing inputs via JSON or files, and stream execution logs directly in the terminal. The CLI supports pushing and pulling entire workspaces or individual resources, with an upcoming default shift to YAML for synchronization. As of version 1.688.0, the package demonstrates a rapid release cadence, with frequent updates incorporating new features and bug fixes, often multiple times per week, indicating active development and continuous improvement. It also offers user management features and shell autocompletion for various shells like Bash, Fish, and Zsh.","status":"active","version":"1.688.0","language":"javascript","source_language":"en","source_url":"https://github.com/windmill-labs/windmill","tags":["javascript"],"install":[{"cmd":"npm install windmill-cli","lang":"bash","label":"npm"},{"cmd":"yarn add windmill-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add windmill-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `windmill-cli` package provides a command-line executable named `wmill`. Its functionalities are accessed via shell commands in your terminal, not direct JavaScript/TypeScript `import` or CommonJS `require` statements into your code.","wrong":"import { wmill } from 'windmill-cli'","symbol":"wmill","correct":"wmill <command>"},{"note":"Workspace management is a core CLI function. To add a workspace, execute `wmill workspace add` in your terminal and follow the interactive prompts. This command is not available as a programmatic import.","wrong":"import { workspace } from 'windmill-cli'; workspace.add();","symbol":"wmill workspace add","correct":"wmill workspace add"},{"note":"Executing Windmill scripts or flows is performed via the CLI. Inputs are passed as a JSON string or from a file using the `--data` flag. The output and logs are streamed directly to the console.","wrong":"import { runScript } from 'windmill-cli'; runScript('u/username/path/to/script', { input: 'value' });","symbol":"wmill script run","correct":"wmill script run u/username/path/to/script --data '{\"input\": \"value\"}'"}],"quickstart":{"code":"npm install -g windmill-cli\n\n# Add a new workspace configuration (follow interactive prompts)\nwmill workspace add\n\n# Example: Running a simple script (replace 'u/your_user/hello_world' with an actual script path)\n# Ensure 'hello_world' exists in your Windmill instance.\nwmill script run u/your_user/hello_world --data '{\"name\": \"Registry Expert\"}'\n\n# Alternatively, pass data from a file:\necho '{\"greeting\": \"Hello from Registry!\"}' > script-inputs.json\nwmill script run u/your_user/another_script --data @script-inputs.json\n\n# Synchronize and pull all workspace resources to your local directory in YAML format\nwmill sync pull --yaml\n","lang":"typescript","description":"Demonstrates how to install the Windmill CLI globally, configure a workspace, execute a Windmill script with data inputs, and pull workspace resources locally."},"warnings":[{"fix":"To ensure future compatibility, begin using the `--yaml` flag explicitly with `wmill sync` commands. If you require JSON, use the `--json` flag, but be aware that YAML will become the default behavior.","message":"The `wmill sync push` and `wmill sync pull` commands will soon default to YAML format for resource synchronization, instead of JSON. Users currently relying on JSON output or input should be aware of this impending change.","severity":"gotcha","affected_versions":">=1.686.0"},{"fix":"When using `wmill init` for custom AI guidance, set the relevant `WMILL_INIT_AI_*_SOURCE` environment variables prior to executing the command. Consult the latest documentation or codebase for the most current variable names and usage.","message":"Customizing AI guidance bundles (e.g., for `wmill init`) currently relies on setting specific internal environment variables like `WMILL_INIT_AI_SKILLS_SOURCE`. This approach might be considered an internal interface and is subject to change without public API warnings.","severity":"gotcha","affected_versions":">=1.686.0"},{"fix":"Regularly update the CLI using `wmill upgrade` to stay current. If unexpected behavior occurs after an upgrade, consult the GitHub release notes for the specific version for any undocumented changes or adjustments.","message":"The Windmill CLI maintains a very rapid release cadence, often deploying multiple new versions (features and bug fixes) within days. This frequent update cycle, while beneficial for new features, can introduce minor behavioral changes not explicitly highlighted as 'breaking' in release notes.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `windmill-cli` is installed globally using `npm install -g windmill-cli` (or `pnpm add -g windmill-cli`, `yarn global add windmill-cli`). Verify your system's PATH configuration to include npm's global executable directory.","cause":"The `windmill-cli` package was not installed globally, or the global npm bin directory is not included in your system's PATH environment variable.","error":"wmill: command not found"},{"fix":"Run `wmill workspace add` to create a new workspace configuration, providing the correct Windmill API endpoint and a valid API token. If a workspace is already configured, use `wmill workspace switch <name>` to ensure the active workspace settings are correct.","cause":"The CLI was unable to establish a connection or authenticate with the configured Windmill instance, typically due to incorrect endpoint URL, an expired API token, or network issues.","error":"Error: Failed to connect to Windmill instance. Check your API token and endpoint."},{"fix":"Verify that the JSON string passed directly is syntactically correct and properly escaped. If using a file, ensure the file path is correct and its content is valid JSON. For reading from stdin, use `-d @-`.","cause":"The `--data` argument provided to a `wmill flow run` or `wmill script run` command contained malformed JSON, or the specified file (`@<filename>`) does not exist or contain valid JSON.","error":"Error: Invalid JSON input for --data. Expected valid JSON string or @<filename>."},{"fix":"Ensure a local PostgreSQL database is running (default connection string `postgres://postgres:changeme@localhost:5432`). Alternatively, set the `DATABASE_URL` environment variable to point to your PostgreSQL instance before executing test commands like `bun test test/`.","cause":"When attempting to run local tests for `windmill-cli`, a PostgreSQL database instance is either not running or the `DATABASE_URL` environment variable is not correctly configured.","error":"Error: PostgreSQL connection failed"}],"ecosystem":"npm","meta_description":null}