Windmill CLI

Common errors

• wmill: command not found

  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.
  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.

• Error: Failed to connect to Windmill instance. Check your API token and endpoint.

  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.
  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.

• Error: Invalid JSON input for --data. Expected valid JSON string or @<filename>.

  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.
  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 @-`.

• Error: PostgreSQL connection failed

  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.
  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/`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install windmill-cli npm
• yarn add windmill-cli yarn
• pnpm add windmill-cli pnpm

Imports

• wmill
  wrong:

  import { wmill } from 'windmill-cli'

  correct:

  wmill <command>

  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.
• wmill workspace add
  wrong:

  import { workspace } from 'windmill-cli'; workspace.add();

  correct:

  wmill workspace add

  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.
• wmill script run
  wrong:

  import { runScript } from 'windmill-cli'; runScript('u/username/path/to/script', { input: 'value' });

  correct:

  wmill script run u/username/path/to/script --data '{"input": "value"}'

  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.

Quickstart

Demonstrates how to install the Windmill CLI globally, configure a workspace, execute a Windmill script with data inputs, and pull workspace resources locally.

npm install -g windmill-cli

# Add a new workspace configuration (follow interactive prompts)
wmill workspace add

# Example: Running a simple script (replace 'u/your_user/hello_world' with an actual script path)
# Ensure 'hello_world' exists in your Windmill instance.
wmill script run u/your_user/hello_world --data '{"name": "Registry Expert"}'

# Alternatively, pass data from a file:
echo '{"greeting": "Hello from Registry!"}' > script-inputs.json
wmill script run u/your_user/another_script --data @script-inputs.json

# Synchronize and pull all workspace resources to your local directory in YAML format
wmill sync pull --yaml