Get Started

August 27, 2026 · View on GitHub

This guide takes you from an empty project to a running Chronicle client that appends and reads events.

Install

Add the client to your mix.exs dependencies:

defp deps do
  [
    {:cratis_chronicle, "~> 2.2"}
  ]
end

Then fetch it:

mix deps.get

You also need a running Chronicle kernel. For local development, the kernel listens on localhost:35000 over TLS, serving an auto-generated self-signed certificate — the client trusts it out of the box, no configuration needed.

Define an event

defmodule MyApp.Events.AccountOpened do
  use Chronicle.Events.EventType, id: "account-opened-v1"
  defstruct [:account_id, :owner_name, :initial_balance]
end

See Event Types for the full guide.

Start the client

Add Chronicle.Client to your application's supervision tree. With otp_app:, it discovers your event types, reactors, reducers, read models and seeders automatically:

defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Chronicle.Client,
        connection_string: "chronicle://localhost:35000",
        event_store: "my-store",
        otp_app: :my_app}
    ]

    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

The client connects in the background and recovers automatically if the connection drops. See Resilience and the Connection Lifecycle.

Append an event

:ok =
  Chronicle.append("account-1", %MyApp.Events.AccountOpened{
    account_id: "account-1",
    owner_name: "Alice",
    initial_balance: 500
  })

Read it back

{:ok, events} =
  Chronicle.EventSequences.EventLog.get_for_event_source("account-1")

Where to next