eventmodeler 0.6.2 → 0.6.4

package/README.md

@@ -1,8 +1,6 @@
 # eventmodeler
 
-CLI tool for interacting with [Event Model](https://eventmodeling.org) files. Query, update, and export event models from the terminal.
-
-Works with `.eventmodel` files created by the [Event Modeling App](https://www.eventmodeling.app).
+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
 
@@ -10,166 +8,298 @@ Works with `.eventmodel` files created by the [Event Modeling App](https://www.e
 npm install -g eventmodeler
 ```
 
-## Quick Start
-
-```bash
-# Open Event Modeling app in browser
-eventmodeler
+Requires Node.js 18 or newer.
 
-# List all slices
-eventmodeler list slices
+## Setup
 
-# Show details of a slice
-eventmodeler show slice "Place Order"
+```bash
+# Authenticate in the browser
+eventmodeler login
 
-# Search for elements
-eventmodeler search "order"
+# Create a cloud model, or use an existing model id from the app
+eventmodeler create model "Ordering"
 
-# Get JSON output instead of XML
-eventmodeler list slices --format json
+# Link the current repo/directory to a model
+eventmodeler init
 ```
 
-## Commands
+`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.
 
-### List Commands
+Useful auth commands:
 
 ```bash
-eventmodeler list slices              # List all slices with status
-eventmodeler list events              # List all events
-eventmodeler list commands            # List all commands
-eventmodeler list chapters            # List all chapters
-eventmodeler list aggregates          # List all aggregates
-eventmodeler list actors              # List all actors
+eventmodeler whoami
+eventmodeler logout
 ```
 
-### Show Commands
+## Common Workflow
 
 ```bash
-eventmodeler show slice <name>        # Show detailed view of a slice
-eventmodeler show event <name>        # Show detailed view of an event
-eventmodeler show command <name>      # Show detailed view of a command
-eventmodeler show chapter <name>      # Show chapter with its slices
-eventmodeler show actor <name>        # Show actor with its screens
+# 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" }
+    }
+  ]
+}'
 ```
 
-### Completeness Commands
+## Read Commands
 
 ```bash
-eventmodeler show completeness <name>       # Show field mapping completeness for any element
-eventmodeler show model-completeness        # Show completeness of all flows in the model
-eventmodeler show aggregate-completeness <name>  # Check if events have the aggregate ID field
+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>
 ```
 
-### Search
+List commands:
 
 ```bash
-eventmodeler search <term>            # Search for entities by name
+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
 ```
 
-### Modify Commands
+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
-# Mark slice status
-eventmodeler mark "Place Order" done
-eventmodeler mark "Cancel Order" in-progress
+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]
+```
 
-# Add scenario to a slice
-eventmodeler add scenario --slice "Place Order" --json '{"name": "Happy path", ...}'
+Element types for `create place`:
 
-# Add field to an entity
-eventmodeler add field --event "OrderPlaced" --json '{"name": "orderId", "type": "UUID"}'
+```text
+command, event, readmodel, screen, processor, external-event,
+aggregate, actor, chapter, context, note, swimlane, slice
+```
 
-# Remove field
-eventmodeler remove field --event "OrderPlaced" --field "legacyId"
+Linked copies are supported for:
 
-# Update field properties
-eventmodeler update field --read-model "OrderSummary" --field "notes" --optional true
+```text
+event, readmodel, screen, external-event
+```
 
-# Map fields between elements
-eventmodeler map fields --flow "OrderPlaced→OrderSummary" --json '[{"from": "total", "to": "totalAmount"}]'
+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>
 ```
 
-### Export
+Mark slice status:
 
 ```bash
-eventmodeler summary                  # Show model summary statistics
-eventmodeler export json              # Export entire model as JSON
+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
 ```
 
-## Output Format
+## 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
+```
 
-By default, output is in XML format (optimized for AI agents). Use `--format json` for JSON output:
+For field mappings:
 
 ```bash
-eventmodeler list slices --format json
-eventmodeler show slice "Place Order" --format json
+eventmodeler map fields '[{"source":"orderId","target":"orderId"}]' --from PlaceOrder --to OrderPlaced
+eventmodeler remove mapping --from PlaceOrder --to OrderPlaced --mapping <mappingId>
 ```
 
-### Setting Default Format
+## Scenarios
 
-Set your preferred default format via:
+Create a full Given/When/Then scenario in one backend transaction:
 
-**Environment variable:**
 ```bash
-export EVENTMODELER_FORMAT=json
+eventmodeler add scenario --slice "Place Order" '<scenario-json>'
+eventmodeler create scenario --slice "Place Order" '<scenario-json>'
 ```
 
-**Config file** (`~/.eventmodeler/config.json`):
+Scenario JSON shape:
+
 ```json
 {
-  "format": "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" }
+  ]
 }
 ```
 
-Priority: CLI flag > environment variable > config file > default (xml)
-
-## Options
+Allowed entry types:
 
-```
--f, --file <path>       Path to .eventmodel file (default: auto-detect)
---format <xml|json>     Output format (default: xml)
--h, --help              Show help message
--v, --version           Show version number
+```text
+given: event, readmodel
+when:  command, event
+then:  event, command, readmodel, error
 ```
 
-## Use Cases
+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"
+```
 
-### For AI Agents
+Primitive example values are strings. Custom fields use JSON objects, and Custom list fields use arrays of objects.
 
-The CLI is designed to work well with AI coding assistants. The XML output format provides structured, readable data that AI agents can easily parse and understand:
+## Screen And Note Details
 
 ```bash
-eventmodeler show slice "Place Order"
+eventmodeler design <screenName> '<excalidraw-json-array>'
+eventmodeler set note-description [noteName] --text "Markdown or plain text"
 ```
 
-### For Code Generators
+## Automation Loop
 
-Use JSON output to build code generators that read your event model:
+The CLI can poll planned slices and run your generator command for each one.
 
 ```bash
-eventmodeler list events --format json | your-codegen-tool
-eventmodeler show slice "Place Order" --format json
+eventmodeler init loop
+eventmodeler loop
 ```
 
-### For CI/CD
+`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.
 
-Check model completeness in your pipeline:
+## Configuration
 
-```bash
-eventmodeler show model-completeness --format json
+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
 ```
 
-## Requirements
+Override endpoints when developing locally:
 
-- Node.js >= 18.0.0
-- A `.eventmodel` file in the current directory (or specify with `-f`)
+```bash
+export EVENTMODELER_BACKEND_URL=http://localhost:8080
+export EVENTMODELER_KEYCLOAK_URL=http://localhost:18180/realms/eventmodeler
+```
+
+## Help Topics
 
-## License
+Task-oriented help is built into the CLI:
 
-MIT
+```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 App](https://www.eventmodeling.app)
-- [Event Modeling](https://eventmodeling.org)
-- [GitHub Repository](https://github.com/theoema/event-modeler)
+- Event Modeling: https://eventmodeling.org
+- GitHub: https://github.com/theoema/event-modeler