Cratis Chronicle CLI Operations

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:

The CLI ships a versioned machine-readable catalog of its own surface, and that catalog is the authority for exact command names on the installed version:

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 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=: a cached access token first, then the context's client id and secret.

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 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.

Where to look

Inspection commands are read-only: diagnose, version, event-stores list, namespaces list, event-types list|show, events get|tail, observers list|show, failed-partitions list|show, projections list|show, read-models list|instances|get|snapshots|occurrences, jobs list|get, recommendations list, subscriptions list, identities list, users list, applications list, and auth status.

Read what comes back

• A failed partition does not retry itself. It stays failed until something clears it, so a stale value is permanent rather than slow. That distinction is the whole diagnosis: "not arrived yet" and "will never arrive" look identical from the outside.
• 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. Clearing the quarantine is an explicit operation, and it is the last step, not the first.

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 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

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 dry run 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

Confirmation prompts do not fire when stdout is not a terminal. The CLI treats a non-interactive session as an implicit yes, so a destructive command run from a script, a pipeline, or an agent harness proceeds without -y and without asking. Never rely on the prompt as the safety mechanism — the authorization above is the safety mechanism.

Not every mutating command prompts, even interactively. jobs stop and jobs resume describe themselves as prompting for confirmation, but no prompt exists in the implementation. users add, applications add, and subscriptions add do not prompt either.

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

• The terminal Workbench (cratis chronicle workbench) presents the same read-only data as a navigable full-screen view; reach for it when you are exploring rather than answering one question.
• 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.