kyvvu doctor

What you'll learn: How to find out, in one command, whether your setup works — and if it doesn't, which part.

---

kyvvu doctor

Runs nine checks and prints one line each. It never stops at the first failure, because the check that explains a failure is usually the one after it.

Usage: kyvvu doctor [OPTIONS]

Options:
  --api-url TEXT    Kyvvu API URL to probe
  --agent-key TEXT  Agent to diagnose (defaults to KV_AGENT_KEY)
  --json            Emit JSON instead of a report

Exit code is 1 when any check failed, 0 when everything passed or only warned — so it works in a CI step or a support reply.

A healthy setup

$ kyvvu doctor --agent-key my-agent
✓ Python              3.13.15 (CPython), minimum 3.10
✓ Versions            kyvvu 0.22.0, kyvvu-engine 0.12.0 (satisfies <1.0.0,>=0.12.0)
✓ .env                /app/.env defines 3 KV_* key(s): KV_AGENT_KEY, KV_API_KEY, KV_API_URL
✓ API                 https://platform.kyvvu.com reachable (200)
✓ Credential          API key valid — [e-mail]
✓ Registration cache  'my-agent' cached, registered at 2026-09-11T11:27:53+00:00 (agent_id=agent_6442dabc)
✓ Policies            15 policy(ies) in effect from the api source (7 at step_execution, enforcing)
✓ Trace sink          https://platform.kyvvu.com
• Local trial         no local trial record (kyvvu installed 2026-09-10)

All checks passed.

The line that matters

Policies is the reason this command exists. A policy count cannot tell apart situations that need completely different fixes — several of them report zero and allow every step:

What you see	What it means	What to do
15 policy(ies) in effect … (7 at step_execution, enforcing)	Working.	Nothing.
0 policies in effect: the api source answered with no policies	Nothing is assigned to this agent.	Restore the bundled baseline: in the dashboard open Manifests, pick the Kyvvu baseline and Assign it, or POST /api/v1/assignments with the bundled manifest_path (listed by GET /api/v1/baseline) and no repo_id. Re-registering will not bring an unassigned baseline back — that is deliberate. See Removing and restoring the baseline.
the api source offered a policy set that cannot be loaded, so nothing was loaded (a failing check)	A policy in the set is unloadable: an unknown rule_type, params that do not match the rule, a duplicate name, a bad regex or the retired scope: key. A set is loaded whole or refused whole, so an agent started here would refuse to start.	Fix the policies listed under the check — each one names its reason.
0 policies in effect: the configured api source could not be read	The fetch failed and there was no cache to fall back on.	Fix the API and Credential checks above.
N policy(ies) in effect, but the set is stale	Enforcing an older set; the last refresh failed.	Check connectivity — the agent is not enforcing what the platform currently says.
N policy(ies) in effect … but none at step_execution	The agent passed one check at registration; every step it takes afterwards is allowed. A fail-open blind spot with a tick on it.	Assign a manifest carrying step_execution policies — the bundled baseline has them.

An unloadable set prints every refusal with its reason, and kyvvu doctor exits non-zero:

$ kyvvu doctor
✗ Policies            the local source offered a policy set that cannot be loaded, so nothing was loaded and an agent started here would refuse to start
                      refused: policies[0] (Never loads): unknown rule_type 'tainted_path_blokc'. It is not in the engine's rule registry. Did you mean 'tainted_path_block'?
                      → Fix the policies listed under this check, then re-run.

Traces going nowhere

The Trace sink check is the tell for the commonest silent failure: an agent that registers, appears in the dashboard, and has an empty Logs page.

$ kyvvu doctor
! Trace sink          stdout (auto, because no policy source is configured here) — steps are printed, not sent to the platform
                      → Set KV_LOG_LOCATION to your API URL, or pass log_location=<api_url>; with KV_API_KEY and an agent key set, 'auto' resolves to the platform on its own.

Working offline

kyvvu doctor needs no credentials at all — being logged out is one of the things it diagnoses. With KV_POLICY_FILE set it reports on a local manifest instead of the platform, so it works the same for a kyvvu serve --policy-file setup.

The local trial record

If you ran kyvvu try --record-trial, the Local trial check reads that opt-in marker and reports how long it took you to get from pip install to a blocked step:

$ kyvvu doctor
• Local trial         3 offline run(s); first 2026-09-11; install to first block: 4m12s
                      → Delete it with `kyvvu try --forget-trial` (~/.kyvvu/try-marker.json).

That marker is opt-in and never transmitted. Nothing sends it anywhere, and declining costs nothing: with no marker, the check is informational and every other command behaves identically.

doctor vs whoami

They sit side by side and answer different questions.

	kyvvu whoami	kyvvu doctor
Question	Who am I, and what would this shell do?	Is anything broken, and what?
Needs a session	Yes — exits 1 without one	No
On a failure	Stops	Keeps going, reports everything
Exit code	1 when logged out	1 only when a check failed
Output	Six stable lines a script can grep	A report

doctor can also resolve something whoami deliberately refuses to guess: whoami only reads this shell's KV_*, so with no KV_AGENT_KEY it qualifies its answer about where traces go. doctor takes --agent-key, so given one it resolves the trace sink for real — and, with credentials, asks the platform what that agent's policy set actually is.

---

Next steps

• kyvvu auth — log in, and what whoami reports

• kyvvu try — enforcement with no account and no network

• kyvvu serve — a local policy evaluation server