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.
Prerequisites
Section titled “Prerequisites”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.
Install it
Section titled “Install it”Pick one installation method. Each makes the cratis command available on your PATH.
brew tap cratis/cratisbrew install cratisHomebrew manages this installation. See updating the CLI when you need a newer version.
Download the pre-built native binary from the latest release and put it on your PATH. Release assets are named with their version, so resolve the version first:
# x64 (Intel/AMD) — swap x64 for arm64 throughout for an ARM machineVERSION=$(curl -fsSL https://api.github.com/repos/Cratis/cli/releases/latest | grep -Po '"tag_name": "v\K[^"]*')curl -Lo cratis.tar.gz "https://github.com/Cratis/cli/releases/download/v${VERSION}/cratis-${VERSION}-linux-x64.tar.gz"tar -xzf cratis.tar.gzsudo mv cratis /usr/local/bin/cratisCheck that the release provides the asset for your architecture. Native binary upgrades require downloading and replacing the binary; cratis update prints instructions rather than replacing it.
With the .NET SDK (10 or newer), install the global tool:
dotnet tool install -g Cratis.CliThis installation is managed by dotnet tool. See updating the CLI for the update command and its side effects.
Check the connection
Section titled “Check the connection”-
Run
cratiswith 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 cratisOn first use, the CLI sets up a
defaultcontext. Without another server configured, Chronicle commands fall back tochronicle://localhost:35000. Environment variables and command flags can override that address, as explained below. -
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-startedLook for a successful connection in the report, not just a zero exit code: this command can return success even when it cannot connect.
Keep it up to date
Section titled “Keep it up to date”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.
How cratis decides where to connect
Section titled “How cratis decides where to connect”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.
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.
Point it at another store
Section titled “Point it at another store”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:
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:
cratis context create staging --server chronicle://staging.example.com:35000/cratis context set stagingChronicle 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.
Two niceties worth a minute
Section titled “Two niceties worth a minute”If you will use the CLI regularly, install tab completion so your shell can finish commands and options:
cratis completions installRestart 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:
cratis initThis 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.
Where to go next
Section titled “Where to go next”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.