---
title: 'Cratis CLI: Chronicle inspection and project creation'
editUrl: https://github.com/Cratis/cli/edit/main/Documentation/index.mdx
description: Cratis CLI inspects Cratis Chronicle events and processing state, discovers Cratis Arc commands and queries, and creates projects from templates.
lastUpdated: 2026-11-05T00:00:00.000Z
---

Cratis CLI gives you the `cratis` command to inspect Cratis Chronicle from a terminal, discover a running Cratis Arc application's commands and queries, or create a project. For Chronicle, use it to trace a stale read model back through observer state and recorded events, including when you are connected over SSH.

## Start here

Follow [Getting started](/cli/getting-started/) for the installation-to-connection tutorial. Once connected, use the [Chronicle command reference](/cli/chronicle/) for lookup or the [operational scenarios](/cli/scenarios/) for a specific investigation. To create an application instead, start with [project creation](/cli/new/).

  [Install and connect](/cli/getting-started/) — Install cratis and verify a Chronicle connection.

  [Look up Chronicle commands](/cli/chronicle/) — Find commands for events, observers, and read models.

  [Investigate a problem](/cli/scenarios/) — Trace a stuck observer, replay a projection, or check appended events.

  [Create an application](/cli/new/) — Choose a template and scaffold a project.

## Why use the CLI

A read model is the state your application queries. If it looks stale, you need to know whether the expected events arrived and whether an observer, the process that handles those events, stopped. `cratis chronicle diagnose` checks the connection, observer state, failed partitions, and recommendations in one report. A failed partition identifies the part of an observer's work that failed; the [scenarios](/cli/scenarios/) take you from that report to the recorded failure and the next investigation command.

When you work with more than one server, save each connection as a named [context](/cli/context/). Switching contexts saves retyping the URL. Before replaying or changing data, confirm your permissions, the selected event store, namespace, target, current state, and documented operational procedure.

## Install

For prerequisites and the full installation procedure, follow the [getting-started tutorial](/cli/getting-started/#install-it). These are the package-manager commands for quick reference.

  **Homebrew**

  ```bash title="Install with Homebrew"
  brew tap cratis/cratis
  brew install cratis
  ```

  **.NET tool**

  ```bash title="Install as a .NET global tool"
  dotnet tool install -g Cratis.Cli
  ```

The .NET tool requires the runtime declared by the current package. Native
release assets and platform coverage vary by release; verify the exact artifact
before installation.

## Connect and inspect

For your first connection check, follow [Getting started](/cli/getting-started/). Connection strings and context files can contain credentials; keep them out of source, public issues, and shared logs.

For a named development connection, the context and diagnostic commands are:

1. Create a named Chronicle connection context.

   ```bash title="Create a development context"
   cratis context create dev --server chronicle://localhost:35000
   ```

2. Select that context.

   ```bash title="Select the context"
   cratis context set dev
   ```

3. Check the connection and processing state.

   ```bash title="Inspect Chronicle health"
   cratis chronicle diagnose
   ```

Read the report for failed checks, then follow the command it names or choose a [scenario](/cli/scenarios/) for the problem you are investigating. Use command help for the options and output available in your installed CLI version.

<a id="current-boundaries"></a>

Before scripting a command, select an output format and bind your parser to the CLI version you use. Output formats can change between versions.

## Product relationship

If you prefer a browser, [Chronicle Workbench](/chronicle/workbench/) is bundled with Chronicle for authorized local inspection of runtime state and for trying supported projection behavior. Use the CLI for terminal inspection and diagnosis of that same runtime.

For application endpoint discovery, [`cratis arc`](/cli/arc/) reads a running Arc application's HTTP catalogs without a Chronicle connection. To start a project, [`cratis new`](/cli/new/) creates application files from a template and attempts to synchronize the template's configured Cratis AI guidance. Neither step is required for inspecting Chronicle.

## Continue

Check the [CLI repository](https://github.com/Cratis/cli) for source and releases, or the [Cratis.Cli package](https://www.nuget.org/packages/Cratis.Cli) for published .NET tool versions. Product documentation covers [Chronicle](/chronicle/) and [Arc](/arc/); the command groups above link to their CLI workflows.

  [CLI source and releases](https://github.com/Cratis/cli) — Repository README, releases, and contribution paths.

  [CLI package](https://www.nuget.org/packages/Cratis.Cli) — Published .NET tool metadata and versions.

  [Chronicle](/chronicle/) — The event-sourcing database and runtime the CLI inspects.

  [Chronicle Workbench](/chronicle/workbench/) — The browser alternative for inspecting Chronicle state.

  [Arc](/arc/) — The CQRS application framework behind the Arc inspection commands.