eventmodeler

Command line client for Event Modeler cloud models. Use it to inspect a model, place elements on the canvas, maintain fields and scenarios, and drive code generation loops from a terminal or agent.

Installation

npm install -g eventmodeler

Requires Node.js 18 or newer.

Setup

# Authenticate in the browser
eventmodeler login

# Create a cloud model, or use an existing model id from the app
eventmodeler create model "Ordering"

# Link the current repo/directory to a model
eventmodeler init

eventmodeler init writes .eventmodeler.json in your project. Most commands read the model id from that file. You can also target an element directly with the global --id <uuid> option when a command accepts an optional name.

Useful auth commands:

eventmodeler whoami
eventmodeler logout

Common Workflow

# Explore the model
eventmodeler show model
eventmodeler list slices
eventmodeler show slice "Place Order"
eventmodeler search order

# Build out the canvas
eventmodeler create place command PlaceOrder --x 120 --y 200
eventmodeler create place event OrderPlaced --x 120 --y 360
eventmodeler create flow --from PlaceOrder --to OrderPlaced

# Add fields
eventmodeler add field PlaceOrder '{"name":"orderId","type":"UUID"}'
eventmodeler add subfield PlaceOrder --field customer '{"name":"email","type":"String"}'

# Create a scenario atomically
eventmodeler create scenario --slice "Place Order" '{
  "name": "happy path",
  "when": [
    {
      "entryType": "command",
      "elementName": "PlaceOrder",
      "fieldValues": { "orderId": "uuid-1" }
    }
  ],
  "then": [
    {
      "entryType": "event",
      "elementName": "OrderPlaced",
      "fieldValues": { "orderId": "uuid-1" }
    }
  ]
}'

Read Commands

eventmodeler show model
eventmodeler show context [name]
eventmodeler show chapter [name]
eventmodeler show slice [name]
eventmodeler show event [name]
eventmodeler show command [name]
eventmodeler show readmodel [name]
eventmodeler show screen [name]
eventmodeler show processor [name]
eventmodeler show external-event [name]
eventmodeler show completeness
eventmodeler summary
eventmodeler search <term>

List commands:

eventmodeler list slices [--chapter <name>]
eventmodeler list events
eventmodeler list commands
eventmodeler list readmodels
eventmodeler list screens
eventmodeler list processors
eventmodeler list external-events
eventmodeler list aggregates
eventmodeler list actors
eventmodeler list chapters
eventmodeler list contexts
eventmodeler list swimlanes
eventmodeler list notes
eventmodeler list scenarios

Output is JSON from the backend SDK. Use eventmodeler help <topic> or command-specific --help for schema examples.

Canvas And Model Editing

Create models, slices, elements, flows, and linked copies:

eventmodeler create model <name>
eventmodeler create slice '<json>'
eventmodeler create place <type> <name> --x <n> --y <n>
eventmodeler create flow --from <source> --to <target>
eventmodeler create place-copy <type> [originalName] --x <n> --y <n>
eventmodeler create move-copy <type> [name] --x <n> --y <n>
eventmodeler create remove-copy <type> [name]

Element types for create place:

command, event, readmodel, screen, processor, external-event,
aggregate, actor, chapter, context, note, swimlane, slice

Linked copies are supported for:

event, readmodel, screen, external-event

Move, resize, rename, and remove existing elements:

eventmodeler move <type> [name] --x <n> --y <n>
eventmodeler resize <type> [name] --width <n> --height <n>
eventmodeler rename <type> <oldName> <newName>
eventmodeler remove <type> [name]
eventmodeler remove flow --from <source> --to <target>

Mark slice status:

eventmodeler mark "Place Order" planned
eventmodeler mark "Place Order" created
eventmodeler mark "Place Order" in-progress
eventmodeler mark "Place Order" blocked
eventmodeler mark "Place Order" done

Fields

Fields are supported on commands, events, readmodels, screens, processors, and external events.

eventmodeler add field [elementName] '{"name":"customerId","type":"UUID"}'
eventmodeler add subfield [elementName] --field <parentFieldName> '{"name":"email","type":"String"}'

eventmodeler update field [elementName] --field <name> --name <newName>
eventmodeler update field [elementName] --field <name> --type <newType>
eventmodeler update field [elementName] --field <name> --optional true
eventmodeler update field [elementName] --field <name> --generated false
eventmodeler update field [elementName] --field <name> --list true
eventmodeler update field [elementName] --field <name> --user-input true

eventmodeler update subfield [elementName] --subfield <id> --name <newName>
eventmodeler update subfield [elementName] --subfield <id> --type <newType>
eventmodeler update reorder [elementName] --field <name> --position <n>
eventmodeler update reorder-subfield [elementName] --subfield <id> --position <n>

eventmodeler remove field [elementName] --field <name>
eventmodeler remove subfield [elementName] --subfield <id>
eventmodeler set aggregate-id [aggregateName] --field-name <name> --field-type UUID

For field mappings:

eventmodeler map fields '[{"source":"orderId","target":"orderId"}]' --from PlaceOrder --to OrderPlaced
eventmodeler remove mapping --from PlaceOrder --to OrderPlaced --mapping <mappingId>

Scenarios

Create a full Given/When/Then scenario in one backend transaction:

eventmodeler add scenario --slice "Place Order" '<scenario-json>'
eventmodeler create scenario --slice "Place Order" '<scenario-json>'

Scenario JSON shape:

{
  "name": "happy path",
  "description": "optional",
  "given": [
    { "entryType": "event", "elementName": "OrderPlaced" }
  ],
  "when": [
    { "entryType": "command", "elementName": "PlaceOrder" }
  ],
  "then": [
    { "entryType": "event", "elementName": "OrderPlaced" },
    { "entryType": "error", "errorType": "Validation", "errorMessage": "Invalid order" }
  ]
}

Allowed entry types:

given: event, readmodel
when:  command, event
then:  event, command, readmodel, error

Example values can be provided in the scenario JSON via fieldValues, or edited later:

eventmodeler add entry --scenario "happy path" --section then --type event --element OrderPlaced
eventmodeler set example --scenario "happy path" --entry <entryId> --type event --field orderId --value uuid-1
eventmodeler set example --scenario "happy path" --entry <entryId> --type event --field tags --values vip,web
eventmodeler set example --scenario "happy path" --entry <entryId> --type event --field address --json '{"city":"NYC"}'
eventmodeler set description --scenario "happy path" --text "Updated description"
eventmodeler set position --scenario "happy path" --section then --entry <entryId> --position 0
eventmodeler remove example --scenario "happy path" --entry <entryId> --type event --field orderId
eventmodeler remove entry --scenario "happy path" --section then --entry <entryId>
eventmodeler remove scenario "happy path"

Primitive example values are strings. Custom fields use JSON objects, and Custom list fields use arrays of objects.

Screen And Note Details

eventmodeler design <screenName> '<excalidraw-json-array>'
eventmodeler set note-description [noteName] --text "Markdown or plain text"

Automation Loop

The CLI can poll planned slices and run your generator command for each one.

eventmodeler init loop
eventmodeler loop

eventmodeler init loop adds a loop block to .eventmodeler.json and creates a sample generate.sh. The generated script marks a slice in progress, exports slice JSON, runs your codegen placeholder, and marks the slice done or blocked.

Configuration

Global config lives at:

~/.eventmodeler/config.json

Project config lives at:

.eventmodeler.json

The production backend is used by default:

https://api.eventmodeler.com

Override endpoints when developing locally:

export EVENTMODELER_BACKEND_URL=http://localhost:8080
export EVENTMODELER_KEYCLOAK_URL=http://localhost:18180/realms/eventmodeler

Help Topics

Task-oriented help is built into the CLI:

eventmodeler help
eventmodeler help build-slice
eventmodeler help write-scenarios
eventmodeler help manipulate-canvas
eventmodeler help linked-copies
eventmodeler help check-completeness
eventmodeler guide json-reference

Links

• Event Modeling: https://eventmodeling.org
• GitHub: https://github.com/theoema/event-modeler