Installation

WOML is installed as a global command because it runs workflow projects rather than becoming a dependency of each application. One installation gives you the woml command, the Bun-based frontend and script host, and the native Rust engine for your platform.

Before you install

You need:

• Bun 1.3.14 or later.
• A supported Linux, macOS, or Windows system.
• A writable project directory for .woml source and local runtime data.

Check Bun first:

bun --version

If Bun is missing, install it from the official Bun documentation before continuing.

Install the CLI

Choose one package manager. Do not install the platform-specific @woml-org/* packages yourself; woml-cli selects the correct native engine automatically.

With npm:

npm install --global woml-cli

With Bun:

bun add --global woml-cli

With pnpm:

pnpm add --global woml-cli

Verify the complete installation

First confirm that your shell can find the command:

woml --version
woml --help

Then create hello.woml:

<woml>
  <workflow id="hello" name="Hello WOML" version="1.0.0">
    <triggers>
      <manual id="start" />
    </triggers>
    <steps>
      <step id="greet" name="Build greeting">
        <script>
          return { message: "Hello from WOML" };
        </script>
      </step>
    </steps>
  </workflow>
</woml>

Validate the file without running its JavaScript:

woml check hello.woml

A successful check confirms that the CLI, frontend compiler, and native model boundary can load the workflow. Run it with woml run hello.woml, press Enter, and press Ctrl+C when you are finished.

Understand local runtime files

During local use, WOML creates a .woml/ directory for durable state, runtime metadata, and logs. This directory is runtime data rather than workflow source. Do not edit its database manually, and normally exclude it from Git:

.woml/

The default durable database is created automatically. You do not need to install or configure a database to complete the tutorials.

Fix command not found

If installation succeeds but woml is unavailable:

1. Close and reopen the terminal.
2. Ask your package manager for its global binary directory.
3. Confirm that directory appears in your PATH.
4. Avoid mixing a root-owned global installation with a user-owned Bun installation.

For Bun, the global executable commonly lives in Bun's bin directory. Confirm the current shell configuration instead of hardcoding a machine-specific path.

Upgrade or pin WOML

Upgrade with the same package manager you used for installation:

npm install --global woml-cli@latest

For a production server, install an exact version so deployment is reproducible:

npm install --global woml-cli@1.0.7

Always verify woml --version after upgrading and run woml check against the workflow directory before restarting production automation.

Continue with the Quick Start.