Use krino

CLI

Reference for krino init, krino report, and krino doctor: what each command does, its options, where it reads traces, and its exit codes.

The krino command reads krino's trace files and helps you set up. Install it next to the library:

Terminal

npm i -D @krinolabs/cli
npx krino --help

Command options and output may change in any release.

krino init

Terminal

npx krino init [--trace-dir <folder>] [--force]

Finds ai or @anthropic-ai/claude-agent-sdk in your package.json.
Writes krino.config.json with your project name and every decision in shadow mode.
Prints the code snippet that wires krino into your host.
Never edits your source files.
Will not overwrite an existing krino.config.json unless you pass --force.

It exits 1 when there is no package.json, when the file is not valid JSON, or when the config already exists. Otherwise it exits 0.

In v0.1, only krino doctor reads krino.config.json. The runtime does not: pass the same projectName and decisionModes to createKrino().

krino doctor

Terminal

npx krino doctor [--project <name>] [--trace-dir <folder>]

It checks:

Node 22 or later.
Your host SDK versions: ai in >=7.0.111 <8, and @anthropic-ai/claude-agent-sdk (tested with 0.3.286).
Whether AI_GATEWAY_API_KEY is set. It never prints the value.
Whether decisions work with the fake provider.
Whether the trace folder is writable, and whether recent traces parse.
The cut-off rate. It warns above 5%.
Cache health. It warns when the cache read share of multi-step runs is below 50%.
Whether a relative traceDirectory points the runtime and the CLI at different folders.

Every warning or failure comes with a fix line. A check with nothing to check yet shows SKIP, which never counts as a pass. It exits 1 on any failure, otherwise 0.

krino report

Terminal

npx krino report [--project <name>] [--trace-dir <folder>] [--since 7d] [--tokens-per-tool 175] [--json]

Per decision and mode, it shows the number of calls, agreement with what your agent did, the estimated cost saved if you enforce (cache reads and writes included), and the latency krino added. Then cache health, the cut-off count, and one "next step" line.

Option	Default	What it does
`--project`	every project	Report on one project.
`--trace-dir`	the runtime's trace folder	Read traces from this folder.
`--since`	`7d`	Only records since a duration (`12h`, `7d`, `2w`) or an ISO date.
`--tokens-per-tool`	`175`	Prompt tokens per tool definition, used for the estimated saving. An estimate, not a measurement.
`--json`	off	Print JSON with a stable shape (`reportSchemaVersion: 1`).

Lines with an unknown schema version, invalid JSON, or the wrong shape are skipped and counted. Colors turn off with NO_COLOR and when output is not a terminal. It exits 1 on bad options or read errors, otherwise 0.

Where the CLI looks for traces

The CLI reads the same folder the runtime writes to. The first that applies wins:

--trace-dir, when you pass it.
traceDirectory in krino.config.json (krino doctor only).
$KRINO_TRACE_DIRECTORY.
$XDG_STATE_HOME/krino/traces/<project>, when XDG_STATE_HOME is an absolute path.
~/.krino/traces/<project>.

A relative traceDirectory can point at two different folders: the CLI resolves it from the config file's folder, the runtime from the process's working folder. Use an absolute path or KRINO_TRACE_DIRECTORY so both use the same folder.