Skip to content
Back to search

woml

Workflow applications as readable documents. Build automations, that can automate anything.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dali-benothmen--woml/badge.svg)](/listings/dali-benothmen--woml)

HTML

<a href="/listings/dali-benothmen--woml"><img src="/api/listings/dali-benothmen--woml/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

WOML requires [Bun](https://bun.sh/) 1.3.14 or later. Install the global CLI with npm:

npm install --global woml-cli

Or install it with Bun or pnpm:

bun add --global woml-cli
pnpm add --global woml-cli

All three commands install the same `woml` executable:

woml --version

Native engines are selected automatically for supported macOS, Linux, and Windows systems. You do not need to install the platform packages or configure a database manually.

Linux packages require glibc 2.31 or newer.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 456 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # WOML: Workflow Orchestration Markup Language
  3. <img src="./assets/woml.png" alt="WOML — Workflow Orchestration Markup Language" width="760">
  4. ### If you can read HTML, you can build workflows, apps, and AI agents with WOML.
  5. **Readable markup for structure. JavaScript for logic. A durable runtime for execution.**
  6. [![npm version](https://img.shields.io/npm/v/woml-cli.svg)](https://www.npmjs.com/package/woml-cli)
  7. [![GitHub stars](https://img.shields.io/github/stars/dali-benothmen/woml.svg?style=social)](https://github.com/dali-benothmen/woml)
  8. [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
  9. [![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)]()
  10. [Website](https://woml.org/) · [Documentation](https://woml.org/docs/) · [Examples](https://woml.org/examples/)
  11. </div>
  12. ## What is WOML?
  13. WOML is an open-source, code-first language and runtime for building automated workflows, backend applications, and AI agents. Describe the process in readable, HTML-inspired markup, use JavaScript for logic, and connect the APIs, services, databases, local tools, and infrastructure involved.
  14. Each `.woml` file combines three parts:
  15. - **Readable structure** — triggers, steps, branches, loops, parallel work, approvals, and policies remain visible as markup.
  16. - **Real code** — inline JavaScript and imported JavaScript or TypeScript modules implement custom behavior without waiting for a built-in connector.
  17. - **Managed execution** — the runtime handles attempts, retries, state, waits, workflow calls, recovery, and execution history.
  18. The workflow source is the program, its readable architecture, and its execution policy. It can live in Git, move through pull requests and CI, and run locally or on infrastructure you control.
  19. Start with one workflow for a local task or webhook. As the work grows, extract reusable modules, call or start other workflows, publish events, and operate the result as a coordinated system without changing its underlying model.
  20. ## What can you build?
  21. | Build | Use WOML to |
  22. | --- | --- |
  23. | **Automated workflows** | Process orders, onboard customers, generate reports, review content, and coordinate human approvals. |
  24. | **Backend applications** | Handle webhooks, expose workflow APIs, run scheduled jobs, and coordinate event-driven services. |
  25. | **AI agents** | Connect models, tools, memory, specialist workflows, and human review in one durable process. |
  26. | **Data pipelines** | Import, validate, transform, classify, and store data with explicit control flow and recovery. |
  27. | **Infrastructure systems** | Run deployment checks, supervise local processes, coordinate infrastructure changes, and respond to incidents. |
  28. ## Why code-first WOML?
  29. - **Read the whole process** — semantic markup keeps execution order, decisions, parallel work, and policies visible from top to bottom.
  30. - **Use code where it belongs** — write JavaScript inline or import JavaScript and TypeScript modules for application-specific logic.
  31. - **Integrate what your system needs** — call APIs, query databases, run approved local tools, and expose project-owned services without waiting for a connector catalog.
  32. - **Grow through composition** — split large systems into reusable workflows that call each other, start background work, and communicate through events.
  33. - **Keep operational history** — durable execution records attempts, decisions, waits, results, and failures so important work can be inspected and recovered.
  34. - **Own the source and runtime** — review workflows in Git and run them on a developer machine, server, container, or infrastructure you control.
  35. ## How WOML works
  36. 1. **Describe the process** in a `.woml` file using triggers, steps, control flow, and runtime policies.
  37. 2. **Connect your tools** with inline JavaScript, imported modules, managed services, secrets, and reusable child workflows.
  38. 3. **Run and operate it** with the WOML runtime, which records durable state and provides inspection, cancellation, recovery, logs, and backups.
  39. ## Installation
  40. WOML requires [Bun](https://bun.sh/) 1.3.14 or later. Install the global CLI with npm:
  41. ```bash
  42. npm install --global woml-cli
  43. ```
  44. Or install it with Bun or pnpm:
  45. ```bash
  46. bun add --global woml-cli
  47. pnpm add --global woml-cli
  48. ```
  49. All three commands install the same `woml` executable:
  50. ```bash
  51. woml --version
  52. ```
  53. Native engines are selected automatically for supported macOS, Linux, and Windows systems. You do not need to install the platform packages or configure a database manually.
  54. Linux packages require glibc 2.31 or newer.
  55. ## Quick Start: Build an Order Router
  56. Create a file named `order-router.woml`:
  57. ```xml
  58. <woml>
  59. <workflow
  60. id="order-router"
  61. name="Order Router"
  62. description="Check inventory and risk concurrently, then route the order."
  63. version="1.0.0"
  64. >
  65. <triggers>
  66. <webhook
  67. id="newOrder"
  68. path="/webhooks/orders"
  69. method="POST"
  70. auth="none"
  71. >
  72. <schema>
  73. {
  74. "type": "object",
  75. "required": ["orderId", "amount", "inStock", "riskScore"],
  76. "properties": {
  77. "orderId": { "type": "string" },
  78. "amount": { "type": "number" },
  79. "inStock": { "type": "boolean" },
  80. "riskScore": { "type": "number" }
  81. },
  82. "additionalProperties": false
  83. }
  84. </schema>
  85. </webhook>
  86. </triggers>
  87. <steps>
  88. <step
  89. id="prepareOrder"
  90. name="Prepare order"
  91. description="Normalize the order received by the webhook."
  92. >
  93. <script>
  94. return {
  95. orderId: context.payload.orderId,
  96. amount: context.payload.amount
  97. };
  98. </script>
  99. </step>
  100. <parallel
  101. id="orderChecks"
  102. name="Run order checks"
  103. description="Check inventory and risk at the same time."
  104. concurrency="2"
  105. on-error="wait-all"
  106. >
  107. <step
  108. id="inventoryCheck"
  109. name="Check inventory"
  110. description="Confirm that the requested item is available."
  111. >
  112. <script>
  113. return { available: context.payload.inStock };
  114. </script>
  115. </step>
  116. <step
  117. id="riskCheck"
  118. name="Check risk"
  119. description="Accept orders with a risk score below seventy."
  120. >
  121. <script>
  122. return {
  123. approved: context.payload.riskScore < 70,
  124. score: context.payload.riskScore
  125. };
  126. </script>
  127. </step>
  128. </parallel>
  129. <step
  130. id="canFulfill"
  131. name="Make decision"
  132. description="Combine the inventory and risk results."
  133. >
  134. <script>
  135. return {
  136. value:
  137. context.steps.inventoryCheck.available &&
  138. context.steps.riskCheck.approved
  139. };
  140. </script>
  141. </step>
  142. <choose
  143. id="orderRoute"
  144. name="Route order"
  145. description="Accept the order or send it for review."
  146. >
  147. <when test="{{context.steps.canFulfill.value}}">
  148. <step id="acceptOrder" name="Accept order">
  149. <script>
  150. return {
  151. status: "accepted",
  152. message: `Order ${context.steps.prepareOrder.orderId} is ready for fulfillment.`
  153. };
  154. </script>
  155. </step>
  156. <result value="{{context.steps.acceptOrder}}" />
  157. </when>
  158. <otherwise>
  159. <step id="reviewOrder" name="Request review">
  160. <script>
  161. return {
  162. status: "review",
  163. message: `Order ${context.steps.prepareOrder.orderId} needs review.`
  164. };
  165. </script>
  166. </step>
  167. <result value="{{context.steps.reviewOrder}}" />
  168. </otherwise>
  169. </choose>
  170. <step
  171. id="response"
  172. name="Build response"
  173. description="Publish one predictable result for the caller."
  174. >
  175. <script>
  176. return {
  177. orderId: context.steps.prepareOrder.orderId,
  178. amount: context.steps.prepareOrder.amount,
  179. ...context.steps.orderRoute
  180. };
  181. </script>
  182. </step>
  183. </steps>
  184. </workflow>
  185. </woml>
  186. ```
  187. Check it without starting the automation:
  188. ```bash
  189. woml check order-router.woml
  190. ```
  191. Then run it:
  192. ```bash
  193. woml run order-router.woml
  194. ```
  195. WOML keeps the automation active and prints its webhook URL together with a generated `curl` command. Trigger it from another terminal:
  196. ```bash
  197. curl --request POST http://127.0.0.1:3000/webhooks/orders \
  198. --header 'content-type: application/json' \
  199. --data '{"orderId":"order-42","amount":240,"inStock":true,"riskScore":18}'
  200. ```
  201. Use `auth="none"` only for local development. Configure authenticated webhooks before exposing an endpoint outside a trusted environment.
  202. ## How the Workflow Runs
  203. ```mermaid
  204. flowchart TD
  205. trigger[POST /webhooks/orders] --> prepare[Prepare order]
  206. prepare --> parallel{Run concurrently}
  207. parallel --> inventory[Check inventory]
  208. parallel --> risk[Check risk]
  209. inventory --> decision[Make decision]
  210. risk --> decision
  211. decision --> route{Route order}
  212. route -->|Accepted| accept[Accept order]
  213. route -->|Needs review| review[Request review]
  214. accept --> response[Build response]
  215. review --> response
  216. ```
  217. ## See the Result
  218. WOML presents each run as an organized, colored terminal report. You will see output like this:
  219. ```text
  220. RUN run_8f21c4 Order Router
  221. ✓ Prepare order 3 ms
  222. Normalize the order received by the webhook.
  223. → { orderId: "order-42", amount: 240 }
  224. ✓ Check inventory 2 ms
  225. → { available: true }
  226. ✓ Check risk 2 ms
  227. → { approved: true, score: 18 }
  228. ✓ Make decision 1 ms
  229. → { value: true }
  230. ✓ Accept order 1 ms
  231. → { status: "accepted", message: "Order order-42 is ready for fulfillment." }
  232. ✓ Build response 1 ms
  233. → { orderId: "order-42", amount: 240, status: "accepted" }
  234. Completed in 10 ms · 6 succeeded
  235. ```
  236. The exact run ID and timings will differ. Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop the active workflow host.
  237. ## What You Just Built
  238. - **`<webhook>`** validated an HTTP request and created a durable workflow run.
  239. - **`context.payload`** exposed the validated trigger input to every script.
  240. - **`<parallel>`** ran two independent checks concurrently and waited for both.
  241. - **`context.steps.<id>`** made completed step results available downstream.
  242. - **`<choose>`** selected one route and published a stable merged result.
  243. - **The terminal experience** showed each step, result, duration, and final outcome.
  244. ## Explore what you can build
  245. Every example below is checked against the current WOML compiler.
  246. | Build | What it demonstrates | Run |
  247. | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------- |
  248. | [Durable run counter](./examples/durableStateWorkflow.woml) | State that survives future runs and process restarts | `woml run examples/durableStateWorkflow.woml` |
  249. | [Personalize a customer list](./examples/forEachWorkflow.woml) | Durable per-item execution, bounded concurrency, and ordered results | `woml run examples/forEachWorkflow.woml` |
  250. | [Social distribution](./examples/forkDistributionWorkflow.woml) | Several independent multi-step branches with an explicit join | `woml run examples/forkDistributionWorkflow.woml` |
  251. | [Telegram approval](./examples/telegramApprovalWorkflow.woml) | Human approval, interactive notification buttons, and durable waiting | `woml run examples/telegramApprovalWorkflow.woml` |
  252. | [Workflow composition](./examples/workflowCallManual/) | One workflow calling another and using its returned result | `woml run examples/workflowCallManual` |
  253. | [Durable external callback](./examples/durableWaits/ciCallback.woml) | A run that releases its worker and resumes from an idempotent CI signal | `woml run examples/durableWaits/ciCallback.woml` |
  254. | [Preview environment saga](./examples/compensationAndCleanup/previewEnvironment.woml) | Explicit rollback and mandatory cleanup for partial infrastructure success | `woml run examples/compensationAndCleanup/previewEnvironment.woml` |
  255. | [Streamed Terraform release](./examples/streamingOutput/) | Live process output, structured progress, review, locking, compensation, and replay | See the example runbook |
  256. | [Local TypeScript module](./examples/moduleWorkflow.woml) | Reusable project code exposed through `services.*` | `woml run examples/moduleWorkflow.woml` |
  257. Provider examples require their documented credentials. Browse the [complete example catalog](./examples/) for webhooks, schedules, intervals, internal events, databases, storage, cache, lifecycle, retries, communication providers, and production deployment.
  258. ## Build larger systems from reusable workflows
  259. A WOML project can begin with one file and grow into a system of focused workflows and modules. Workflows can call another workflow and wait for its result, start independent work in the background, or publish events that other workflows consume.
  260. Create a project with workflow discovery and operator-owned configuration already in place:
  261. ```bash
  262. woml init my-project
  263. cd my-project
  264. woml check
  265. woml test
  266. ```
  267. The generated `workflow.json` keeps workflow discovery, policies, reviewers, and execution targets reviewable while secret values remain outside source control. The same project model supports local execution, durable artifacts and waits, rich approvals, infrastructure policies, streamed output, OpenTelemetry, and authenticated remote targets. Remote work never silently falls back to the coordinator.
  268. Read the [project manifest reference](./docs/project-manifest.md), follow the [infrastructure-agent tutorial](./docs/infrastructure-agent-tutorial.md), or use the [operator runbook](./docs/combined-developer-experience-operator-runbook.md).
  269. ## Built for real execution
  270. ### Connect and extend
  271. - **Embedded JavaScript** — use `context.payload`, `context.steps`, `attempt`, `services`, and explicitly referenced `secrets` inside scripts.
  272. - **Project-owned modules** — import local JavaScript or TypeScript and expose reusable logic through `services.*`.
  273. - **Managed capabilities** — use supervised HTTP, SQLite/PostgreSQL, storage, cache, state, events, workflow calls, and communication services.
  274. - **Production triggers** — start work manually or from webhooks, schedules, intervals, internal events, Slack, Telegram, Discord, and WhatsApp.
  275. ### Structure complex work
  276. - **Explicit control flow** — combine sequential steps, durable bounded item loops, parallel groups, choices, switches, and concurrent forks with explicit joins.
  277. - **Reusable workflows** — call a workflow for a result, start background work, and coordinate independent components through events.
  278. - **Human decisions** — pause durably for approval, preserve the decision, and continue through approved or rejected routes.
  279. - **Runtime policies** — define concurrency, rate limits, queues, timeouts, retries, and lifecycle hooks beside the workflow they govern.
  280. ### Continue through failure
  281. - **Durable execution** — preserve attempts, decisions, waits, results, failures, and operation identities across process restarts.
  282. - **Retries and idempotency** — declare retry behavior while retaining stable attempt and operation identities.
  283. - **Durable waits and signals** — suspend without holding a worker and resume the same run from timers or authenticated callbacks.
  284. - **Locks, leases, and fencing** — serialize shared-resource work and reject stale owners with monotonic fencing tokens.
  285. - **Compensation and cleanup** — correct proven partial success, always run cleanup, and stop for review when an external effect is ambiguous.
  286. ### Operate on your infrastructure
  287. - **Inspection and recovery** — inspect activity, follow logs, cancel runs, retry verified-safe work, back up state, and prune old history.
  288. - **Streaming output and progress** — follow supervised process output live, reconnect by cursor, and replay bounded redacted records.
  289. - **Portable deployment** — run the same project locally or against authenticated remote targets without silent fallback.
  290. - **Cross-platform runtime** — install one CLI that selects the appropriate native Rust engine automatically.
  291. When an interrupted external effect has an uncertain outcome, WOML marks it **ambiguous** instead of retrying it automatically. Inspect the real system with `woml dispatch inspect`, then record an audited decision with `woml dispatch reconcile`.
  292. ## Common Commands
  293. ```bash
  294. woml check workflows/ # Parse, validate, and compile
  295. woml run workflows/ # Activate workflows in the foreground
  296. woml run workflows/ --background # Activate them in the background
  297. woml inspect # Open the colored runtime inspector
  298. woml list # List workflows and recent runs
  299. woml get run_... # Inspect one run and its event history
  300. woml cancel run_... # Cancel a pending or running workflow
  301. woml recover run_... --retry action-id # Resume a verified-safe corrective attempt
  302. woml logs workflow-id --follow # Follow live process output and progress
  303. woml secrets set API_TOKEN # Store a secret without printing it
  304. woml backup backups/latest # Back up the durable state store
  305. woml prune --before 30d --dry-run # Preview retention cleanup
  306. ```
  307. See the [CLI reference](./docs/cli-reference.md) for all commands, flags, exit behavior, and machine-readable output.
  308. ## VS Code Experience
  309. The [WOML extension](./woml-vscode/) gives `.woml` files HTML-style markup highlighting, embedded JavaScript syntax, highlighted runtime bindings such as `context` and `services`, reference-expression highlighting, snippets, and a dedicated file icon.
  310. <div align="center">
  311. <img src="./assets/vscode.png" alt="WOML workflow open in Visual Studio Code" width="1100">
  312. </div>
  313. The extension follows your existing VS Code theme instead of requiring a separate WOML color theme.
  314. ## Build WOML with AI coding agents
  315. WOML is structured source code, so coding agents can create and change workflows in the same environment as the rest of your project. The **WOML Skill** teaches agents the language structure, runtime bindings, control-flow patterns, services, secrets, and validation workflow they need to produce real `.woml` files without inventing syntax.
  316. ```text
  317. Use the WOML skill to build an order-processing workflow that starts from a
  318. webhook, checks inventory and risk concurrently, and routes the result.
  319. ```
  320. The generated workflow remains readable, reviewable in Git, and verifiable with `woml check` before it runs.
  321. For Claude Code, install the complete skill in the current project:
  322. ```bash
  323. mkdir -p .claude/skills/woml
  324. curl -fsSL https://github.com/dali-benothmen/woml/releases/latest/download/woml-skill.tar.gz \
  325. | tar -xz -C .claude/skills/woml
  326. ```
  327. For Codex and other clients that use the Agent Skills project convention:
  328. ```bash
  329. mkdir -p .agents/skills
  330. cp -R skills/woml .agents/skills/woml
  331. ```
  332. **[View the WOML Skill and installation guide →](./skills/woml/)**
  333. ## Documentation and Examples
  334. - [Getting started](./docs/getting-started.md)
  335. - [Language reference](./docs/language-reference.md)
  336. - [CLI reference](./docs/cli-reference.md)
  337. - [Services and capabilities](./docs/woml-services.md)
  338. - [Locks and leases](./docs/woml-locks-and-leases.md)
  339. - [Compensation and cleanup](./docs/woml-compensation-and-cleanup.md)
  340. - [Run local tools safely](./docs/woml-process.md)
  341. - [Stream output and report progress](./docs/woml-streaming-output-and-progress.md)
  342. - [Preserve files as Durable Artifacts](./docs/woml-durable-artifacts.md)
  343. - [Modules](./docs/woml-modules.md)
  344. - [Communication providers](./docs/woml-communication-providers.md)
  345. - [Production deployment](./docs/woml-production-deployment.md)
  346. - [Complete example catalog](./examples/)
  347. ## Support and Security
  348. Use [GitHub Discussions](https://github.com/dali-benothmen/woml/discussions) for questions and [GitHub Issues](https://github.com/dali-benothmen/woml/issues) for reproducible bugs. Follow the [support guide](./SUPPORT.md) when sharing diagnostics, and report vulnerabilities privately according to the [security policy](./SECURITY.md).
  349. ## Contributing
  350. Contributions are welcome, including bug reports, documentation improvements, tested examples, provider work, compiler changes, and runtime improvements. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
  351. ## License
  352. WOML is released under the [Apache License 2.0](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.