Get started

Your first .em.hcl model

Install the CLI, write a small model, validate it, and render it locally.

1 · Install the CLI

Download a release archive, or build from source with Go 1.25 or newer.

Option A: download a release

curl -LO https://github.com/event-modeling-hcl/eventmodeling-hcl/releases/latest/download/eventmodeling-hcl_0.4.0_linux_amd64.tar.gz curl -LO https://github.com/event-modeling-hcl/eventmodeling-hcl/releases/latest/download/checksums.txt sha256sum -c checksums.txt tar -xzf eventmodeling-hcl_0.4.0_linux_amd64.tar.gz

Swap linux_amd64 for darwin_amd64, darwin_arm64, linux_arm64, windows_amd64, or windows_arm64 as needed, and the version number for whatever the releases page currently lists. With GitHub CLI 2.49.0 or newer, you can also verify the archive was actually produced by this repository's release workflow:

gh attestation verify eventmodeling-hcl_0.4.0_linux_amd64.tar.gz --repo event-modeling-hcl/eventmodeling-hcl

Option B: build from source

git clone https://github.com/event-modeling-hcl/eventmodeling-hcl.git cd eventmodeling-hcl go build -o eventmodeling-hcl ./cmd/eventmodeling-hcl

Either way, confirm it runs:

./eventmodeling-hcl version

2 · Write your first model

Save this as pet.em.hcl. It's the same minimal model used throughout this site — one bounded context, one Event, one State Change workflow:

bounded_context "pet_management" { title = "Pet Management" aggregate "pet" { } field_type "pet_id" { type = "Int" id_attribute = true example = 5 } event "pet_added" { title = "Pet Added" aggregate = aggregate.pet field "pet_id" { } } } state_change "add_pet" { title = "Add Pet" screen "add_pet_form" { title = "Add Pet Form" to = [command.add_pet_command] } command "add_pet_command" { title = "Add Pet" aggregate = aggregate.pet_management.pet fields = [field_type.pet_management.pet_id] to = [event.pet_management.pet_added] } }

3 · Validate it

./eventmodeling-hcl validate pet.em.hcl

A valid document prints:

pet.em.hcl valid

A diagnostic instead would look like file:line:column: Severity EMxxx: message. See the quality page for what's a hard error versus a warning worth a second look.

4 · Render the canvas

./eventmodeling-hcl diagram pet.em.hcl -o pet.html wrote pet.html

pet.html is a single self-contained file — no external dependencies, no build step. Open it directly in a browser.

Optional: publish the diagram

The model and rendered canvas are files, so you can commit them beside the code and host the canvas with GitHub or GitLab Pages:

git add pet.em.hcl pet.html git commit -m "Add pet-registration event model" git push

Keeping the model in the repository means it can be versioned and reviewed with the code.

Using a coding agent? It can draft, validate, fix, and render a model before human review. See Using .em.hcl with coding agents.
Learn the method Language reference