kurrent-tools

kurrent-tools

A developer toolkit for KurrentDB, built around debugging and observing event streams. One static binary, two verb groups plus an MCP server, and a shared decode/render core that every tool inherits.

kurrent-tools inspect  ls | peek | schema | topology | trace   # understand my data
kurrent-tools diagnose lag | diff | replay                     # diagnose a problem
kurrent-tools mcp                                              # serve read-only tools to an agent

Eight tools. Seven are read-only; replay is the only one that writes, and it only ever writes to a separate scratch instance you name explicitly.

---

Install

You need Go 1.26+ and (for the demo data and tests) Docker.

From the GitHub repo

git clone https://github.com/kurrent-io/kurrent-tools.git
cd kurrent-tools

# Build a local binary in the repo:
go build -o kurrent-tools ./cmd/kurrent-tools
./kurrent-tools --help

# …or install it onto your PATH (into $(go env GOBIN), or $(go env GOPATH)/bin):
go install ./cmd/kurrent-tools
kurrent-tools --help        # if that dir is on your PATH

A single go build produces a single static binary — no runtime dependencies.

Prefer not to clone? Install straight from the module:

go install github.com/kurrent-io/kurrent-tools/cmd/kurrent-tools@main

The examples below use kurrent-tools (on PATH). If you built locally instead, use ./kurrent-tools.

---

Connect

The toolkit speaks kurrentdb:// and kurrentdb+discover:// only — never the legacy esdb:// scheme. The connection string is resolved in this order:

1. --conn "<connection-string>" (a global flag, valid on every command)
2. the KURRENTDB_CONNECTION_STRING environment variable
3. the default, kurrentdb://localhost:2113?tls=false (a local insecure node)

# explicit:
kurrent-tools --conn "kurrentdb://localhost:2113?tls=false" inspect peek order-1001

# via environment (handy for a shell session):
export KURRENTDB_CONNECTION_STRING="kurrentdb://localhost:2113?tls=false"
kurrent-tools inspect peek order-1001

# default (no flag, no env) — assumes a local node on :2113:
kurrent-tools inspect peek order-1001

?tls=false is required for a local insecure node; omit it (or use tls=true) when connecting to a secured cluster. Credentials in the URL (user:pass@host) are redacted from logs.

---

Local KurrentDB + demo data

The repo ships a single-node KurrentDB and a deterministic seed so you have realistic streams to point the tools at.

docker compose up -d          # local insecure node on :2113 (container kurrent-tools-db)
go run scripts/seed.go        # seed order/payment/shipment sagas + schema drift + a binary blob

The seed writes:

• order-1001, order-1002 — full order → payment → shipment sagas with $correlationId/$causationId chains (saga-1001, saga-1002).
• order-1003 — a cancelled saga (shorter), so diff has divergence to show.
• payment-1001/1002, shipment-1001/1002 — the downstream stages.
• customer-501/502/503 — the customer category with schema drift (501 has name; 502/503 have firstName/lastName/tier).
• telemetry-001 — a binary SensorBlob payload (proves decoding never crashes).

Categories present: order, payment, shipment, customer, telemetry. The seed is idempotent (re-running is a no-op) and prints a manifest of the deterministic event IDs the tools reference — e.g. the saga-1001 root (OrderPlaced) is e6678748-08bc-5a2d-b278-09be89315931.

---

The eight tools

Global flags on every command: --conn, --json (machine-readable / JSONL), --no-color, --log-level debug|info|warn|error (default warn).

inspect ls [pattern] — discover what streams exist

The primitive you reach for first: ls to find a stream, then peek to look. Reads the $streams standard projection; an optional glob filters by name.

kurrent-tools inspect ls                      # every (user) stream, sorted
kurrent-tools inspect ls 'order-*'            # glob: order-1001, order-1002, order-1003
kurrent-tools inspect ls 'payment-100?'       # ? matches one char
kurrent-tools inspect ls --category order     # streams in the 'order' category ($ce-order)
kurrent-tools inspect ls --system             # include $-prefixed system streams
kurrent-tools inspect ls --limit 50 --json    # cap results; JSONL: {"stream":"order-1001"}

Flags: --category <name>, --system (hidden by default), --limit N (default 500). If the $streams projection isn't running, ls prints how to enable standard projections rather than silently returning nothing.

inspect peek <stream> — decode and display recent events