eventmodeler

Command line client for Event Modeler cloud models. Use it to inspect a model and edit it from a terminal or agent.

Every model is a sheet model: an Excel-style grid where columns are slices and rows are typed lanes. Layout is derived from the grid, so you never author coordinates. You address things by spreadsheet coordinates (A, 2, B2, B2.1).

Installation

npm install -g eventmodeler
# or run it without installing
npx eventmodeler --help

The CLI is a native binary. npm installs the one for your machine as an optional dependency (@eventmodeler/cli-<os>-<cpu>); the eventmodeler command is a small Node.js shim that runs it, so Node.js 18 or newer is needed. Prebuilt binaries: macOS (Apple Silicon and Intel), Linux (x64 and arm64, static, any distribution) and Windows (x64).

If your install skips optional dependencies (--omit=optional, --no-optional), the binary is missing and the CLI says so; reinstall without the flag. To run a binary you built yourself (cargo build --release -p em-cli in rust/), point EVENTMODELER_BINARY at it.

Setup

# Authenticate in the browser
eventmodeler login

# Link the current repo/directory to a model (pick one, or create a new one)
eventmodeler init

eventmodeler init writes .eventmodeler.json in your project. Commands read the model id from that file; override it per invocation with --model <id>.

eventmodeler whoami      # who am I logged in as, and which endpoints
eventmodeler status      # which model is this directory linked to
eventmodeler disconnect  # unlink (removes .eventmodeler.json)
eventmodeler logout

The command surface depends on connection state: until a model is linked (or --model is passed), only login, logout, whoami, dev, init, status, disconnect and list are available. --help always shows exactly what is valid right now.

Reading

eventmodeler sheet show              # the model's sheet as a compact 2D grid (name one when there are several)
eventmodeler sheet show Checkout     # one sheet
eventmodeler sheet show Checkout B2  # drill into a cell (fields, scenarios)
eventmodeler sheet show --json       # lossless machine-readable structure

eventmodeler summary                 # entry counts per scope
eventmodeler list events             # every entry in one scope, as JSON
eventmodeler snapshot                # the whole model as JSON in model.eventmodel (read-only export)

list accepts: commands, events, readModels, screens, processors, externalEvents, slices, aggregates, actors, chapters, contexts, swimLanes, notes, flows, scenarios.

Editing

All editing is under eventmodeler sheet:

eventmodeler sheet new Checkout                    # a new sheet, or scaffold from a file with --from
eventmodeler sheet insert slice ...                # add a slice (column)
eventmodeler sheet insert actor|interaction|swimlane|specification|notes <name>   # add a lane (row)
eventmodeler sheet insert command B2 PlaceOrder    # put an element into a cell
eventmodeler sheet update B2.1 '{"name":"PlaceOrderV2","fields":[...]}'
eventmodeler sheet move B2.1 --to C2
eventmodeler sheet reorder A --to 3
eventmodeler sheet flow B2.1 C3.1                  # connect two elements
eventmodeler sheet copy C3.1 --to D3               # linked copy of an event/read model/screen/external event
eventmodeler sheet slice span A --to C             # slices can span several columns
eventmodeler sheet note B2 "text"
eventmodeler sheet rm B2.1                         # element; or a column (A), or a lane (2)
eventmodeler sheet delete Checkout --yes

A cell holds at most one element; scenarios are the exception and may stack in specification cells. Widen a slice (sheet slice span, sheet slice split) to make room. Use eventmodeler sheet <command> --help for the exact arguments and options.

Every edit is sent to the server as one change: it lands whole or not at all, and the CLI prints once the server has confirmed it. If someone else changed the same cell in the meantime, the server refuses the edit and the CLI says why.

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:4000
# or: eventmodeler dev on

Before each command the CLI checks npm for a newer version and offers to update. EVENTMODELER_UPDATE=never (or --no-update-check) turns that off; EVENTMODELER_UPDATE=auto updates without asking.

Changes in 0.8

• The CLI is now a native binary (Rust, on the same model core as the server) instead of a Node.js program. Commands, options, output and exit codes are unchanged.
• Sign in again once: run eventmodeler login. Sign-ins from 0.7 were issued by the previous server and are no longer accepted; the CLI tells you when yours is one of them. Your .eventmodeler.json files and settings carry over as they are.
• Edits are confirmed by the server before the CLI prints them, and a refused edit is reported (exit 1) instead of silently dropped.

Links

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