Run Workflows

woml run activates automation. Unlike a one-shot script, it normally stays alive because a workflow automation must still be present when the next webhook, schedule, message, event, or manual occurrence arrives.

woml run workflow.woml
woml run parent.woml child.woml
woml run workflows/

What activation does

The runtime treats every supplied file and directory as one deployment unit. Before it says it is ready, WOML:

1. Parses and validates every runnable workflow and dependency.
2. Resolves modules and known workflow-call targets.
3. Pins immutable compiled definitions for future run recovery.
4. Opens durable state and recovers eligible existing runs.
5. Starts provider connections and network listeners behind a closed gate.
6. Opens trigger admission only after every required component is ready.

If activation fails, WOML closes the partial startup. It does not intentionally leave half of the workflows accepting traffic.

Trigger and run output

For a manual workflow, the terminal tells you to press Enter. For a webhook or event, it prints the endpoint and a copyable request example. For schedules and communication providers, it shows the relevant schedule or provider status.

Every accepted occurrence receives a durable run ID. The same runtime can show many runs over time:

RUN  run_8f21c4                                  24 Aug 2026 · 10:42:13

  01  ✓  Validate order                                      18 ms
  02  ✓  Calculate total                                     31 ms

✓ Completed in 49 ms · 2 succeeded

Editing a file does not mutate a run already in progress. Stop and restart the deployment to activate the new definition for future runs.

Run one file, several files, or a directory

Use multiple explicit files when they call or start one another:

woml run order-api.woml calculate-risk.woml send-receipt.woml

For a larger deployment, place runnable workflows in one directory:

woml run workflows/

Loading multiple workflows in one process gives services.workflows.call() and start() a shared durable authority. Each called workflow still gets its own run ID and event history.

Useful options

Useful options include --config, --host, --port, --state, --trigger, --resume, --approval-port, --json, --verbose, and --color=auto|always|never.

woml run workflows/ \
  --config woml.runtime.json \
  --state ./data/workflow-history.sqlite \
  --color=always

Use --trigger only when WOML needs help choosing among manual triggers. --resume addresses a recoverable run using its stored immutable definition; it is not a general way to inject new data into an arbitrary run.

Stop safely

Press Ctrl+C for a graceful foreground shutdown. Under systemd, Docker, or Kubernetes, keep WOML in the foreground and let the supervisor own process lifetime.

Use --background only on a directly managed workstation or VPS. Foreground and background modes use the same Rust engine and durability model; the difference is who owns the process.