Skip to content

Cratis CLI: install and connect to Chronicle

Cratis CLI provides the cratis terminal command for inspecting Cratis Chronicle events and diagnosing processing failures. This tutorial takes you from installation to a connection report for a running store, then shows how to select another server. You can work entirely from a terminal, including over SSH; Chronicle Workbench provides the browser alternative. Neither requires you to write inspection code.

You need a running Chronicle store you are authorized to inspect. If you do not have one, follow the Chronicle get-started first. With no connection overrides, the CLI targets chronicle://localhost:35000.

Choose Homebrew, a native release binary, or the .NET global tool for installation. The .NET tool targets .NET 10; its installation command below uses the .NET SDK.

Pick one installation method. Each makes the cratis command available on your PATH.

Install with Homebrew
brew tap cratis/cratis
brew install cratis

Homebrew manages this installation. See updating the CLI when you need a newer version.

  1. Run cratis with no arguments in an interactive terminal to see the active context, a named connection, and its configured server URL. This displays saved settings without attempting a connection.

    Check the active connection
    cratis

    On first use, the CLI sets up a default context. Without another server configured, Chronicle commands fall back to chronicle://localhost:35000. Environment variables and command flags can override that address, as explained below.

  2. Test the server connection with cratis get-started. It also prints a guide to inspection commands.

    Test the connection and get a tour
    cratis get-started

    Look for a successful connection in the report, not just a zero exit code: this command can return success even when it cannot connect.

Follow Update Cratis CLI for the update procedure, installation-specific limits, template refreshes, and Stage image updates. Updating is separate from proving your first connection.

Chronicle commands use the first server setting they find: the --server flag, then CHRONICLE_CONNECTION_STRING, then the active context, and finally chronicle://localhost:35000. This order matters when a command reaches a different server from the one saved in your context.

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

With no overrides or configured server, the CLI uses the local address. The environment variable and --server flag let you select a server for automation or a one-off command without changing the saved context.

Use a context to save a server address you will need again. You can change default or leave it for local work and add a separate context for each environment.

With default selected as the active context, change its saved 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, 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

Chronicle commands now use staging unless the environment variable or an explicit --server overrides it. Run cratis get-started to check the connection before inspecting that store. For CI and containers, you can set CHRONICLE_CONNECTION_STRING instead of switching saved contexts. See Context for the full workflow.

If you will use the CLI regularly, install tab completion so your shell can finish commands and options:

Install shell completions
cratis completions install

Restart your shell after installing completions. Use --shell bash|zsh|fish|powershell to select a shell explicitly.

If a coding assistant needs the command catalog, run cratis init inside your project. It generates CHRONICLE.md and assistant integration files describing the CLI’s commands:

Set up AI tooling
cratis init

This is optional and separate from connecting to Chronicle. The generated catalog is a snapshot; after upgrading, use cratis init --refresh to regenerate it. Use --no-context when you must not add a CHRONICLE.md reference to a shared, generated instruction file. See LLM context for the catalog surface.

For a first look at the store, open the Chronicle command reference and list its event stores before choosing what to inspect. If you already have a failure to investigate, follow a scenario for a stuck observer, projection replay, or checking appended events.

Use Context when you need more saved connections. For an existing installation, Update Cratis CLI explains the update procedure and its side effects.