CLI Reference

Every command. Real captured output, not a mockup.

klaro init

Scaffolds klaro.config.ts with the recommended pipeline (retries + budget + secrets + pii + logging). Also creates .klaro/project.json.

klaro doctor

Provider connectivity (a real, zero-cost GET against each provider's own models endpoint), retry health, a cost-optimization recommendation grounded in your recorded spend, and a health score.

────────────────────────────
AI Runtime Health
────────────────────────────

✓ Node.js version          v22.23.1
✓ OpenAI Connected         authenticated
✓ Claude Connected         authenticated
⚠ Gemini Connected         GEMINI_API_KEY not set
✓ Retry Policy             4% of calls needed a retry — healthy
✓ .klaro/ local storage    exists

⚠ gpt-4-turbo costs 98% more than gpt-4o-mini for comparable output
  Potential savings: $0.98 based on your recorded usage

Health Score: 92/100

klaro inspect [-n, --limit <n>]

Recent requests: latency, cost, redactions. Default limit 10.

klaro stats

"Today's AI health": retries saved, secrets/PII removed, cost, latency, budget remaining, health score -- all computed from what actually happened.

────────────────────────────
Today's AI Health
────────────────────────────

✓ Retries Saved       1
✓ Secrets Removed     1
✓ PII Removed         2
✓ Cost Today          $0.07
✓ Average Latency     491 ms
✓ Budget Remaining    $49.93

Health Score: 80/100

(4 calls, 1 failed, all-time spend $0.07)

klaro explain [callId]

Plain-language narration of a call's full retry/redaction history. Most recent call by default, or a specific one by its ID (or 8-char prefix).

klaro explain — call bbb22222 (8/7/2026, 4:06:49 PM)

  Failed after 430ms — 429 rate limited
  ↓
  Retry triggered — attempt 2
  ↓
  Succeeded in 500ms

2 attempts, 930ms total, succeeded in the end.

klaro simulate

Runs rate-limit/500/timeout/bad-JSON/injection/huge-prompt scenarios through YOUR configured pipeline (imported from klaro.config.js). Requires a compiled/plain-JS config -- run via `node --import tsx` for a .ts config.

klaro simulate — testing your configured pipeline against common failure modes

✓ 429 Rate Limit       Completed after 2 attempts (351ms)
✗ 500 Server Error     Failed after 3 attempts -- Service unavailable (1286ms)
✗ Timeout              Failed after 3 attempts -- Request timed out (756ms)
✓ Bad JSON             Returned unvalidated: "{not valid json" -- add validation() to catch this (0ms)
✓ Prompt Injection     Completed after 1 attempt (0ms)
✓ Huge Prompt          Completed after 1 attempt (2ms)

klaro benchmark

Sends a real test call to every provider you have a key for (OpenAI, Claude, Gemini, and Ollama if running locally) and compares latency, cost, and reliability.

Benchmarking Providers

| Provider | Model | Latency | Cost | Status |
|---|---|---|---|---|
| OpenAI | gpt-4o-mini | — | — | ⚠ OPENAI_API_KEY not set |
| Claude | claude-3-5-haiku-latest | — | — | ⚠ ANTHROPIC_API_KEY not set |
| Gemini | gemini-1.5-flash | — | — | ⚠ GEMINI_API_KEY not set |
| Ollama | llama3.2 | — | — | ⚠ not running locally (expected on :11434) |

klaro dashboard [-p, --port <port>]

Opens a local web dashboard at localhost:3456 (or your chosen port). See the full Local Dashboard docs.

klaro report [-f, --format md|json|html|pdf] [-o, --out <path>]

Exports the same data as the dashboard (health score, spend, recent requests) as a file -- markdown for a PR/README, JSON for your own tooling, HTML to open in a browser, PDF to share with your team. Text formats print to stdout if --out isn't given; PDF always writes a file (klaro-report.pdf by default). Default format is md.

$ klaro report --format md

# KlaroShield AI Runtime Report

Generated 2026-08-08T06:02:38.179Z — @klaroshield/sdk v0.3.0

## Summary

| Metric | Value |
|---|---|
| Health Score | 73/100 |
| Total Calls | 3 |
| Failed Calls | 1 |
| Retries Saved | 1 |
| Secrets Removed | 0 |
| PII Removed | 1 |
| Avg Latency | 383ms |
| Spend (month to date) | $0.0200 |
| Budget Cap | $50 |
...

klaro telemetry status | enable | disable

Shows exactly what's collected and whether telemetry is on, or toggles it. status is the default subcommand.

Telemetry

Status: Enabled

Data collected:
✓ SDK version
✓ Anonymous installation ID
✓ Enabled middleware
✓ CLI usage

Never collected:
✗ Prompts
✗ Responses
✗ API keys
✗ Secrets
✗ PII

klaro version

Prints the installed SDK/CLI version and Node.js version, read from package.json at runtime.