# Cratis Chronicle CLI Operations

> Use when inspecting a running Chronicle store or performing an authorized store operation through the cratis CLI. Not for source-local defects, MCP tool selection or the browser Workbench.

- Skill: `cratis/cratis-chronicle-cli-operations-2` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add cratis/cratis-chronicle-cli-operations-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cratis/cratis-chronicle-cli-operations-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Cratis (https://skillmd.com/u/cratis)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/cratis/cratis-chronicle-cli-operations-2

---


# 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 draws on these sources:

| Package | Purpose |
| --- | --- |
| `Cratis.Cli` | command effects, confirmations, contexts, output and command tree |
| `Cratis.Chronicle` | the CLI's Chronicle client package; server authentication configuration and development-client registration |

Observer removal, partition-quarantine clearing, server-bound login and diagnose scope
are operational. Read [command effects](references/command-effects.md)
when classifying a mutation or confirmation.

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.

Read [project tooling](references/project-tooling.md) for embedded release notes,
cached templates, managed MCP registration and install-only versus harness AI
conformance checks. Updating instructions does not run those behavior checks.

## 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. The CLI does not restrict that fallback to localhost; acceptance depends
on the server's authentication configuration and registered clients, not its
address. Development builds can register that client automatically; do not rely
on a remote server rejecting it. 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. Requires cratis CLI 3.21.0 for login to keep the token; an older CLI discarded it, so log in again if `auth status` shows no token. 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/main/Source/Cli/Commands/Chronicle/ChronicleSettings.cs)
and [authentication](https://github.com/Cratis/cli/blob/main/Documentation/chronicle/auth.md).
Server evidence:
[authentication configuration](https://github.com/Cratis/Chronicle/blob/main/Source/Kernel/Core/Configuration/Authentication.cs)
and [development-client registration](https://github.com/Cratis/Chronicle/blob/main/Source/Kernel/Core/Setup/Authentication/AuthenticationService.cs)
(`EnsureDefaultClientCredentials`, compiled under `DEVELOPMENT`).

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
  `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 or later, 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.

Read [recovery outcomes and namespace comparison](references/recovery-and-comparison.md)
for refusal-aware job actions, retained-job deletion, observer-wide failed-partition
recovery, exact manual stream reopening and bounded metadata comparison.

## 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`,
  `retry-failed-partitions`, `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 jobs delete`
- `chronicle streams closed reopen` — exact manual scope repair with a reason
- `chronicle recommendations perform`, `chronicle recommendations ignore`
- `chronicle subscriptions add`, `chronicle subscriptions remove`
- `chronicle users add`, `chronicle users remove`
- `chronicle applications add`, `chronicle applications remove`

Check the installed catalog's `effect` before acting; it is the authority. `chronicle login/logout` are `local`, while
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.

## Compare a namespace with its model

`cratis screenplay conform-namespace` is read-only and sits outside the `chronicle` group and its guard: it reads the registry, observers and event metadata of one namespace and compares them with a `.play` model. Use it for a post-deploy check; the procedure and exit codes are in `cratis-screenplay-render-and-gap-fill` [post-deploy check](../cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md). Its exit `4` is a refused read: obtain a context with read access, never widen permissions.

## 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.
- Narrator (VS Code extension `cratis.narrator`) browses stores, event types, observers and projections from the editor, using the same contexts in `~/.cratis/config.json`.
- 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.

