# 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

```bash
npm install -g eventmodeler
```

Requires Node.js 18 or newer.

## Setup

```bash
# 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:

```bash
eventmodeler whoami
eventmodeler logout
```

## Common Workflow

```bash
# 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

```bash
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:

```bash
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:

```bash
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`:

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

Linked copies are supported for:

```text
event, readmodel, screen, external-event
```

Move, resize, rename, and remove existing elements:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

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

Scenario JSON shape:

```json
{
  "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:

```text
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:

```bash
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

```bash
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.

```bash
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:

```text
~/.eventmodeler/config.json
```

Project config lives at:

```text
.eventmodeler.json
```

The production backend is used by default:

```text
https://api.eventmodeler.com
```

Override endpoints when developing locally:

```bash
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:

```bash
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