> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/cli-reference/doctor.md). # 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 ```bash $ 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 — you@company.com ✓ 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](/policy-authoring/bundled-baseline.md#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: ```bash $ 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. ```bash $ 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=; 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`](/cli-reference/serve.md) setup. ### The local trial record If you ran [`kyvvu try --record-trial`](/cli-reference/try.md), 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: ```bash $ 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](/cli-reference/auth.md) — log in, and what `whoami` reports * [kyvvu try](/cli-reference/try.md) — enforcement with no account and no network * [kyvvu serve](/cli-reference/serve.md) — a local policy evaluation server