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 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:
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:
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 initreports the mismatch and--refreshfixes 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 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:
--server <CONNECTION_STRING>- the
CHRONICLE_CONNECTION_STRINGenvironment variable - the active context's server in
~/.cratis/config.json 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
and authentication.
Server evidence:
authentication configuration
and development-client registration
(EnsureDefaultClientCredentials, compiled under DEVELOPMENT).
Prefer a named context over repeating a connection string:
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 tojson-compactwhen an AI-agent environment is detected,plainwhenNO_COLORis set,jsonwhen stdout is redirected, andtableotherwise.-q/--quietprints 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
plainfor large listings; JSON repeats every field name on every row. Preferjson/json-compactforshow/getcommands 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
IsQuarantinedis 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: ChronicleDocumentation/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-quarantineclears only the observer.observers clear-partition-quarantine <observer> <partition>needs Chronicle 19.29.0 or later, resets the retry budget and retries unless--no-retryis given; handler side effects may repeat.retry-partitionexits non-zero when quarantined or not failed.jobs resumeresumes Stopped jobs, not Failed.
Read recovery outcomes and namespace comparison 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-quarantinechronicle 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 handlerchronicle jobs stop,chronicle jobs resume,chronicle jobs deletechronicle streams closed reopen— exact manual scope repair with a reasonchronicle recommendations perform,chronicle recommendations ignorechronicle subscriptions add,chronicle subscriptions removechronicle users add,chronicle users removechronicle 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:
- Name the exact server context, event store, namespace, observer, partition, event sequence, or job that will change.
- Capture its exact pre-state and the failure evidence that justifies the operation.
- 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.
- Show the intended change (and a dry run where supported) and obtain explicit authorization for that exact target and action.
- 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. 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-inspectionoffers 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.