cratis-chronicle-cli-operations git:20261012.24c79a0A

Immutable. This exact content never changes and is served at /api/v1/blob/b9a81692aab53511.

---
name: cratis-chronicle-cli-operations
description: Inspect and operate a running Chronicle server with the cratis CLI - contexts and connection resolution, machine-readable output, failed partitions, observers, event sequences, read models, projections and jobs, and the authorization discipline for replay, retry, quarantine clearing and other mutations. Use when the question is about the state of a live store rather than source code. Do not use to diagnose a defect that reproduces locally in source.
license: MIT
---

# Operate a running Chronicle with the `cratis` CLI

Source code says what *should* happen. When the question is what *is* happening
in a live store — a projection that will not move, an observer that stopped, an
event you are not sure was appended — read the server instead of the code.

## Verified product sources

This skill is verified against these exact sources:

| Package | Version | Purpose |
| --- | --- | --- |
| `Cratis.Cli` | `3.53.1` | command effects, confirmations, contexts, output and command tree |
| `Cratis.Chronicle` | `19.32.0` | the CLI's Chronicle client package |

Re-verified at `Cratis/cli v3.53.1`: since 3.2.0, observer removal,
partition-quarantine clearing, server-bound login and broader diagnose scope
have changed operational guidance. Read [command effects](references/command-effects.md)
when classifying a mutation or confirmation; it cites the exact tag.

The CLI ships a **versioned machine-readable catalog of its own surface**, and
that catalog is the authority for exact command names, `effect` and
`requiresConfirmation` on the installed version. Treat every effect other than
`read-only` (including unknown values) as a state change:

```bash
cratis llm-context          # every command, option and argument as JSON
cratis llm-context --schema # the JSON Schema for that document
cratis <group> --help       # the same, one group at a time
```

Do not guess a command name from this file. This skill covers *when to reach for
the CLI and how to read what comes back*; the catalog covers *what to type*.

## Install and set up

`cratis` is a .NET tool published as `Cratis.Cli` with the command name
`cratis`. Install it with `dotnet tool install -g Cratis.Cli`, or through
Homebrew, or from a release binary. Follow with `cratis completions install`.

Once per project, so every agent working it can reach the store:

```bash
cratis init                 # detects the AI tools in use and writes project context
cratis init --refresh       # re-capture after upgrading the CLI
```

Two things worth knowing before running it:

- The embedded catalog is a **snapshot**, not a live lookup. After a CLI upgrade
  it still describes the older surface; `cratis init` reports the mismatch and
  `--refresh` fixes it.
- If the repository's instruction file is supplied by a shared package or a
  generated adapter, pass `--no-context`. Keep project-specific Chronicle
  connection guidance in a repository-owned project context file; never patch
  packaged or generated bytes.

## Reach the right server

The connection string resolves in this exact order:

1. `--server <CONNECTION_STRING>`
2. the `CHRONICLE_CONNECTION_STRING` environment variable
3. the active context's server in `~/.cratis/config.json`
4. `chronicle://localhost:35000`

Credentials are composed separately, and only when the resolved string carries
no embedded `user:pass@` and no `apiKey=` (embedded credentials win): use a cached
login token only for its issuing server and while valid (more than one minute
before expiry), then context client id/secret, then the built-in development
client, which non-local servers reject. An expired matching login without
client credentials raises `LoginSessionExpired` (exit 4), not a silent fallback.
A login belonging to another server is not sent; a once-per-process stderr
notice explains the mismatch.

Use `cratis chronicle login <user>` (`--secret` or prompt), `chronicle logout`
and `chronicle auth status -o json` (`tokenServer`, `loginMatchesServer`). Login
refuses multi-host and `chronicle+srv://` targets. CLIs before 3.21.0 discarded
the login token; log in again after upgrading. Context values can be changed
with `context set-value server|event-store|namespace|client-id|client-secret`.
Keep secrets out of logs and committed configuration.
Evidence: [ChronicleSettings.cs](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/ChronicleSettings.cs)
and [authentication](https://github.com/Cratis/cli/blob/v3.53.1/Documentation/chronicle/auth.md).

Prefer a named context over repeating a connection string:

```bash
cratis context create <name> --server chronicle://<host>:35000
cratis context set <name>
cratis context show
```

A context also carries `--event-store` and `--namespace` defaults; both can be
overridden per command with `-e` and `-n`. The event store defaults to
`default` and the namespace to `Default`.

**Be deliberate about which store you are pointed at.** The same commands read
production and a local container, and several of them mutate. `cratis context
show` before anything that writes; `--debug` prints the resolved config path,
context, redacted connection string, and RPC timing to stderr.

## Choose the output format

There is one output flag, `-o` / `--output`, with values `table`, `plain`,
`json`, `json-compact`, and `auto`. **There is no `--json` flag.**

- `auto` (the default) resolves to `json-compact` when an AI-agent environment
  is detected, `plain` when `NO_COLOR` is set, `json` when stdout is redirected,
  and `table` otherwise.
- `-q` / `--quiet` prints identifiers only, one per line — what you want when
  piping one command into another. Combined with a JSON format it yields a JSON
  array of identifiers.
- Prefer `plain` for large listings; JSON repeats every field name on every row.
  Prefer `json`/`json-compact` for `show`/`get` commands where you need the
  nested structure.

Exit codes are stable and worth branching on: `0` success, `1` not found, `2`
connection error, `3` server error, `4` authentication error, `5` validation
error; `6` is `changes_pending` for `render --check`, not Chronicle commands.
JSON errors carry an `error` code such as `not_found`, `connection_error`,
`server_error`, `authentication_error` or `validation_error`.

## Where to look

| Question | Where to look |
| --- | --- |
| Is the server healthy at all? | `cratis chronicle diagnose`; `--all-namespaces`, `--all-event-stores`, `--watch --interval <seconds>`; non-zero for unhealthy, quarantined or incomplete checks |
| Why has this read model stopped updating? | `chronicle failed-partitions list --observer <id>` — the error is on the partition, not in the log |
| An observer is quarantined — why? | `chronicle failed-partitions show <observer> <partition> --detailed`, with attempt history |
| Did this event actually get appended? | `chronicle events get --event-type <type> --event-source-id <id>` (`events tail` returns only the highest sequence number — not a count, not the events) |
| What is this event's shape in the store? | `chronicle event-types list`, then `chronicle event-types show <type>` |
| Is this projection registered? | `chronicle projections list`, then `chronicle projections show <id>` |
| What does the read model actually hold? | `chronicle read-models get <read-model> <key>`, or `read-models instances` |
| Is a replay or migration still running? | `chronicle jobs list`, then `chronicle jobs get <id>` |
| What does the server itself recommend? | `chronicle recommendations list` |

Classify inspection through `effect=read-only` in `cratis llm-context`, not a
remembered allowlist. `chronicle report-error` is cataloged read-only, but opens
a browser issue form; the harness guard deliberately blocks that external UI
action.

`read-models get|snapshots|instances <READ_MODEL>` takes the **Identifier** column
of `read-models list`, not the container name. `events get` accepts `--sequence`,
`--from`, `--to`, `--event-source-id` and `--event-type` (comma-separated, optional
`Type+gen`). It has no limit option: bound `--from`/`--to` and prefer `-o plain`.
The catalog recommends plain for `event-types list`, `projections list` and
`read-models instances`, and json-compact for `read-models get`.

## Read what comes back

- **A failed partition is not necessarily quarantined.** Eligible failures retry
  automatically under the configured budget; quarantined partitions stop retrying.
  Missing `IsQuarantined` is Unknown, not healthy. A stale value can mean lag or a
  stopped partition: inspect attempts and observer state rather than guessing.
  Observer clear does not clear partition quarantine. Source: Chronicle
  **v19.50.1**, `Documentation/concepts/observers.mdx`.
- **Fix the cause before replaying.** Replaying into an unfixed handler fails the
  same way and buries the original error under a newer one.
- **A quarantined observer does not resume by itself.** A quarantine ends when
  an operator clears it, or when the observer is subscribed again — for an
  application observer, when the client reconnects, for example after a
  redeploy. Clearing the quarantine is an explicit operation and the last step,
  not the first. A redeploy that restarts the client can also end the quarantine
  as a side effect, so check the observer's state before and after a redeploy.

- **Observer and partition quarantine are separate.** `observers clear-quarantine`
  clears only the observer. `observers clear-partition-quarantine <observer> <partition>`
  needs Chronicle 19.29.0+, resets the retry budget and retries unless `--no-retry`
  is given; handler side effects may repeat. `retry-partition` exits non-zero
  when quarantined or not failed. `jobs resume` resumes Stopped jobs, not Failed.

## Before you change anything

Default to read-only inspection. A request to diagnose a live store does not
authorize replay, retry, removal, quarantine clearing, or another mutation.

These commands mutate the running store:

- `chronicle observers replay`, `replay-partition`, `retry-partition`,
  `clear-quarantine`
- `chronicle observers remove` — destructive across every namespace of the event
  store: definition, state, handled counts, failures and projection definition;
  read model data stays. Refused while running or subscribed, no force flag.
- `chronicle observers clear-partition-quarantine` — may retry the handler
- `chronicle jobs stop`, `chronicle jobs resume`
- `chronicle recommendations perform`, `chronicle recommendations ignore`
- `chronicle subscriptions add`, `chronicle subscriptions remove`
- `chronicle users add`, `chronicle users remove`
- `chronicle applications add`, `chronicle applications remove`

This is the v3.53.1 surface, not the authority for later versions; check the
catalog's `effect` before acting. `chronicle login/logout` are `local`, while
`chronicle workbench` is `destructive` because its keys can mutate the store.

Where the Cratis hooks are installed, this boundary is enforced: a `PreToolUse` guard on shell
commands blocks every `cratis chronicle` command that is not on its read-only allowlist, unknown
commands and the interactive `workbench` included, with or without `--yes`. When it blocks, do not
retry or work around it; report the exact command, the target context or server, and what it
changes and why, and ask. A person who authorizes the mutation runs it, or sets
`CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` in the environment the agent harness starts from.

Before any of them:

1. Name the exact server context, event store, namespace, observer, partition,
   event sequence, or job that will change.
2. Capture its exact pre-state and the failure evidence that justifies the
   operation.
3. Prepare the repository-approved inverse or safe compensation when one exists;
   stop when the effect cannot be safely reversed unless the owner separately
   authorizes that irreversible operation.
4. Show the intended change (and a dry run where supported) and obtain explicit
   authorization for that exact target and action.
5. Re-read the target immediately before mutation and stop on drift.

### Two confirmation traps

**Destructive commands fail closed outside a terminal.** Every command with a
confirmation prompt — `observers replay`, `observers replay-partition`,
`observers retry-partition`, `observers clear-quarantine`,
`observers clear-partition-quarantine`, `observers remove`, `jobs stop`,
`jobs resume`, `recommendations perform`, `recommendations ignore`,
`users remove`, `applications remove`, `subscriptions remove` — asks
interactively, and when the session is **not** interactive (a script, a
pipeline, an agent harness) it does *not* proceed: it writes
"Re-run the command with --yes to confirm the operation" and exits with the
validation error code. `--yes` is therefore the only way a non-interactive run
performs one of these. It is confirmation, **not user authorization**; check
`requiresConfirmation` independently from `effect` in the installed catalog. Declining
the interactive prompt exits successfully having done nothing.

**Additive commands do not prompt.** `users add`, `applications add` and
`subscriptions add` run without confirmation in every mode.

Reaching for `--yes` to silence a prompt you have not read is how the wrong
store gets replayed. A failed partition you have not yet explained is not a
thing to clear: read it, fix the handler, then replay. Clearing it first
destroys the evidence and the same failure returns on the next event.

## What the CLI cannot do

There is no `delete`, `purge`, `redact`, or `revise` command. Event redaction
and revision are browser Workbench operations. Treat a request to "remove an
event with the CLI" as a request that needs a different tool and a separate
authorization.

## Related

- `cratis-chronicle-mcp-inspection` offers read-mostly inspection/design-time
  tools and job control only; replay, retry and observer recovery are CLI work.
- The terminal Workbench (`cratis chronicle workbench`) presents the same data
  with mutating keys; a human at a terminal uses it, not an agent harness.
- The browser Workbench owns redaction, revision, and event-type authoring.
- Source-level diagnosis belongs in the application's own diagnostic workflow;
  start there when the symptom reproduces locally, and start here when it is
  only visible on a running server.