Talk to us

Miragon AIDesign

bpmn-cliYour agent edits the model, not the XML.

A command line tool and Claude Code plugin for BPMN 2.0. It keeps your hand-drawn layout and checks the deploy rules of Camunda 7, CIB seven, Operaton or Camunda 8 before the engine does.

Get started
GitHub
Talk to us
bpmn-cli 0.7.0
bpmn new order.bpmn --name "Order handling" --target camunda7created process Process_OrderHandling "Order handling"bpmn add order.bpmn start "Order received"bpmn add order.bpmn service "Reserve stock" \ --after Event_OrderReceivedbpmn add order.bpmn end "Done" --after Activity_ReserveStockwritten: order.bpmnbpmn validate order.bpmn --strictW_C7_DEPLOY_IMPLEMENTATION Activity_ReserveStock:serviceTask Activity_ReserveStock has no implementation(camunda:class, delegateExpression, expression,type=external or a connector); the engines refuse the file(Give it one: `bpmn set <file> Activity_ReserveStockcamunda:type=external camunda:topic=<topic>` (orcamunda:delegateExpression=${...}, camunda:class=...,camunda:expression=${...}).)

The problem

Most of the BPMN XML an agent writes is diagram coordinates

When an agent models or changes a process today, it writes the BPMN XML itself. Every coordinate costs tokens and is a chance to break the file, and shapes your team placed by hand in Camunda Modeler get moved. Read as raw XML, a large model no longer fits into the agent's context.

Today

  • The agent writes the XML, diagram coordinates included
  • Shapes your team placed by hand get moved
  • A large model as raw XML no longer fits the agent's context
  • The engine finds a missing implementation at deploy time

With bpmn-cli

  • The agent names the element and the operation, and bpmn-cli writes the XML
  • Your layout stays, and new elements go next to their neighbours
  • A compact text view without coordinates, or only the part around one id
  • The deploy rules of your engine are checked before you deploy

How it works

Four steps, every element addressed by its id

The agent never touches a coordinate. bpmn-cli draws a new file and keeps an existing drawing.

  1. Read

    bpmn show prints the model as compact text without coordinates. With --around <id> it prints one part.

  2. Change

    bpmn add, set or connect change one element by its id, and bpmn apply sends several changes as one batch.

  3. Look

    bpmn render draws a PNG without a browser. With --problems it numbers the layout problems in the image.

  4. Check

    bpmn validate --strict checks the deploy rules and your project's .bpmnlintrc, and exits with code 5 on any warning, so a pipeline stops.

Findings

Each finding names the command that fixes it

For the session at the top of this page, one bpmn set gives the service task an external topic, and the next check passes.

bpmn set order.bpmn Activity_ReserveStock camunda:type=external camunda:topic=reserve-stock
bpmn validate order.bpmn --strict   # valid, 0 warning(s)

What you get

An ordinary BPMN file, checked before the engine sees it

Every change runs one pipeline: load, apply, validate, lay out, then write. The result opens in the tools your team already uses.

  • Opens where you model

    An ordinary .bpmn file with a laid-out diagram, for Camunda Modeler and bpmn-js.

  • All or nothing

    A change that would add a structural error is refused, and the file stays as it was.

  • Small Git diffs

    Elements a change did not touch keep their exact text.

  • Descriptive ids

    New elements get ids such as Activity_ReserveStock, never hashes or running numbers. An id convention in your .bpmnlintrc sets their prefixes and case.

  • Requirements on the step

    With bpmn set <file> <id> doc="...", the agent keeps the requirement text on the step.

  • Deploy rules per engine

    Camunda 7, CIB seven and Operaton share one profile. Camunda 8 has its own, with a FEEL syntax check.

Get started

Start in Claude Code or at the shell

Install the CLI and build a first model, or add the Claude Code plugin. The bpmn-cli docs have both.

Get started

Status

Where bpmn-cli stands on 14 October 2026

bpmn-cli is at 0.7.0, released to npm on 14 October 2026. It is pre-1.0, and minor versions still bring breaking changes (0.3.0, 0.4.0, 0.5.0 and 0.7.0 did), so pin the version you run. The repository is public under the MIT licence.

  • No hosted playground

    The CLI runs on your machine through npm or npx.

  • No MCP server of its own

    An agent calls the CLI, and designIQ uses it as a library.

  • Models what you describe

    It captures a described process as a valid model. It does not elicit or prioritise requirements.

  • Opt-in inside designIQ

    designIQ's semantic BPMN editing on bpmn-cli is opt-in since designIQ v5.3.0 and off by default for now.

Proof you can open

Everything here is public

Where it fits

bpmn-cli in the lifecycle

bpmn-cli serves Design, and its deploy checks reach into Implement. It starts from a description in the conversation or from an existing .bpmn file from Camunda Modeler, bpmn-js or a designIQ content repository.

Docs

The full reference is in the docs

Let your agents model BPMN in your team's repo.

Tell us which engines you deploy to and where your models live today. Together we check whether bpmn-cli fits the way your team works.

Talk to us

A 30-minute first call.