A command line tool that lets an AI agent (or a human at a shell) edit BPMN 2.0 models semantically: it names elements and operations, and the CLI keeps the drawing. No BPMN XML, no diagram coordinates.
The documentation is at miragon.github.io/bpmn-cli.
A language model writes its answer token by token, so the time and the cost of a change grow with the text it has to produce. BPMN XML is a lot of text, most of it diagram coordinates. An agent that edits the XML itself is slow, and every coordinate it writes is a chance to break the file.
bpmn-cli turns this around: the agent says what should change, in one short command, and the CLI writes the XML and the drawing. What you get:
- Fast, because the agent writes little. One short command replaces kilobytes of XML.
- Cheap to read. The agent reads a compact text view of the model instead of the XML, so large models fit into its context.
- Correct by construction. The agent names elements and changes; references, ids and coordinates are the CLI's job.
- Careful with your drawing. A diagram made in Camunda Modeler or bpmn-js stays as it is; new elements are fitted in next to their neighbours.
- Ready to deploy. Camunda 7 and Camunda 8 settings are set by name and checked before you deploy.
Requires Node 22.12+.
npm install -g @miragon/bpmn-cli # puts `bpmn` on your PATH
brew install miragon/tap/bpmn-cli # or with Homebrew (pulls in Node)
bpmn guide --short # the agent cheat sheet (`bpmn guide` for all of it)
$ bpmn new order.bpmn --name "Order handling"
$ bpmn add order.bpmn start "Order received"
$ bpmn add order.bpmn userTask "Check invoice" --after Event_OrderReceived
$ bpmn add order.bpmn end "Done" --after Activity_CheckInvoice
$ bpmn show order.bpmn
process Process_OrderHandling "Order handling" executable
startEvent Event_OrderReceived "Order received" -> Activity_CheckInvoice (Flow_OrderReceivedToCheckInvoice)
userTask Activity_CheckInvoice "Check invoice" -> Event_Done (Flow_CheckInvoiceToDone)
endEvent Event_Done "Done"
problems: none
The result is a normal .bpmn file that opens in Camunda Modeler / bpmn-js with a laid-out
diagram. A worked session builds a complete
process step by step.
| Task | Commands |
|---|---|
| Read a model | show, find, metrics |
| Change the process | new, add, connect, set, remove, retype, move, order, ext |
| Change several things at once | apply (a batch of ops as JSON) |
| Format the diagram | place, align, color, label, route, space, tidy, compact, layout |
| Look at the diagram | render (PNG or SVG, no browser) |
| Check before deploying | validate (also runs the project's .bpmnlintrc) |
| Ask the CLI itself | guide, kinds, --help |
Details: command reference.
This repository is also a Claude Code plugin
marketplace. Its skill bpmn makes Claude use this CLI whenever a request creates or touches a
BPMN model, instead of writing BPMN XML by hand.
/plugin marketplace add Miragon/bpmn-cli
/plugin install bpmn-cli@miragon-bpmn
Details: Claude Code plugin, and the plugin itself in plugins/bpmn-cli.
Models can target Camunda 7 (including CIB seven and Operaton) or Camunda 8. The CLI sets the platform's implementation details and validates them against its deploy rules.
Details: Camunda 7 and Camunda 8.
A project's bpmnlint configuration (.bpmnlintrc) runs in bpmn validate and in every write: the
agent sees the findings its change added and fixes them in the same batch, instead of in CI. Where
it runs @miragon/rules/element-id-naming, the ids bpmn-cli generates follow its prefixes and case
(bpmn show <file> --conventions lists them).
Details: bpmnlint.
The package is also a library that edits BPMN in memory, in Node and in the browser.
Details: library use, validators, migrating between versions.
The docs site, miragon.github.io/bpmn-cli, is built from docs/:
- Command reference: every command with its options
- Reference: ids, kinds, triggers, placement, set keys, output, errors and exit codes
- Ops JSON: the batch format of
bpmn apply - Layout and formatting: layout modes and the diagram-only commands
- The contract and its limits: what the CLI guarantees, what a write changes, limitations
- Camunda 7 and Camunda 8: platform settings with worked examples
- bpmnlint: the project's
.bpmnlintrcin validate and every write - A worked session: one process from an empty file to a validated model
- Library use and migrating
- Validators: a library host's own checks inside the write
- For maintainers, in the repository only: testing and releasing
See CONTRIBUTING.md.
MIT © Miragon GmbH.