Skip to content
Cratis Cratis Cratis

Getting started with the CLI

You’ve got a Chronicle store running — maybe the local one from the Chronicle get-started, maybe a staging server a colleague set up. Things are happening inside it: events are landing, projections are folding them into read models, reactors are firing. Right now the only way to see any of that is to write code. Let’s fix that.

cratis is a terminal window into a running store. In the next couple of minutes you’ll install it, point it at your Chronicle, and run one command that proves the connection and shows you around. After that, looking at events, observers, or read models is a single command each — never a query.

Prerequisites

Section titled “Prerequisites”
  • Nothing extra to install the CLI itself — the steps below give you the cratis binary.
  • A running Chronicle store to connect to — cratis get-started connects to a Chronicle server, so have one running first. The Chronicle get-started brings a local one up with docker compose up in about a minute; against that local store there’s nothing to configure — the CLI finds it on its own.

Install it

Section titled “Install it”

Pick the install that matches your machine. However you do it, you end up with the same cratis binary on your PATH.

  1. Install the CLI.

    Install with Homebrew
    brew tap cratis/cratis
    brew install cratis

    Upgrade later with brew upgrade cratis.

  2. Prove it’s there. Run cratis with no arguments. It prints the connection it’s pointing at — the active context’s name and the server URL it will talk to:

    Check the active connection
    cratis

    The first time you run any cratis command, it quietly creates a default context aimed at chronicle://localhost:35000 — so on a local box this already points somewhere sensible. We’ll come back to what a context is.

  3. Connect and look around. cratis get-started does two things: it checks it can actually reach the server, then prints a guided summary of the commands you’ll reach for most, grouped by what you’re trying to do.

    Test the connection and get a tour
    cratis get-started

    If it reports a successful connection, you’re done — the CLI is installed and talking to your store.

How cratis decides where to connect

Section titled “How cratis decides where to connect”

That worked with zero configuration, which is worth understanding rather than taking on faith. Every command needs one thing: a server to talk to. cratis resolves it by walking a short list of sources, top to bottom, and using the first one that’s set:

set
not set
set
not set
set
none
--server flag

(this one command)
the server cratis talks to
CHRONICLE_CONNECTION_STRING

(environment variable)
the active context
default

chronicle://localhost:35000

On your machine nothing above the default is set, so it lands on chronicle://localhost:35000 — your local store. That’s why “install and go” just works. The two layers above the context — the environment variable and the --server flag — are escape hatches for automation and one-off commands; you’ll meet them when you need them.

Point it at another store

Section titled “Point it at another store”

A context is a named connection. You already have default; real work usually means a couple more — staging, production — so you can switch between them without retyping URLs.

Repoint the default at a different server:

Change where 'default' points
cratis context set-value server chronicle://myserver.example.com:35000/

Or keep default for local and add a named context per environment, then switch the active one:

Add and switch to a staging context
cratis context create staging --server chronicle://staging.example.com:35000/
cratis context set staging

From here on, every command talks to staging until you switch back. For CI and containers, skip contexts entirely and set CHRONICLE_CONNECTION_STRING in the environment — it wins over the active context but yields to an explicit --server. Full details are on the Context page.

Two niceties worth a minute

Section titled “Two niceties worth a minute”

Tab completion. Let your shell finish commands and options for you:

Install shell completions
cratis completions install

It detects your shell automatically (override with --shell bash|zsh|fish|powershell); on Windows it writes the hook to your PowerShell $PROFILE. Restart your shell to pick it up.

Teach your AI assistant about your store. Run cratis init inside a project and the CLI writes a CHRONICLE.md describing every command it can run, installs instruction files for Claude Code, GitHub Copilot, Cursor, and Windsurf, and adds a chronicle-diagnose slash command — so your assistant can help operate the store too:

Set up AI tooling
cratis init

Refresh the embedded snapshot after a CLI upgrade with cratis init --refresh. For the same catalog as raw JSON, run cratis llm-context (add --schema for its JSON Schema).

Recap

Section titled “Recap”

In a couple of minutes you installed cratis, watched it find your local Chronicle through the default context, and confirmed the connection with cratis get-started. You also saw the one rule that governs every command — flag, then environment variable, then context, then the local default — so nothing about where it connects is a mystery anymore.

Where to go next

Section titled “Where to go next”
  • Actually look at something — the Chronicle commands browse events, observers, and read models in a live store.
  • Solve a real problem — the Scenarios walk through fixing a stuck observer, replaying a projection, and verifying events were appended.
  • Manage connections properly — the Context page covers creating, switching, and inspecting contexts in depth.