Skip to main content
Version: MVP

Doctor Diagnostics

5 min readFor operatorsUpdated 2026-05-22

What you'll do

Run craik doctor to health-check your Craik home, identity, credentials, model selection, gateway posture, channel pairings, endpoint safety, and local file permissions — without making a live API call, writing a receipt, or starting a daemon. By the end, you'll know exactly what's configured, what's broken, and what to fix first.

Doctor is read-only unless you ask for fixes

craik doctor inspects existing local state and environment variables. It does not create CRAIK_HOME, initialize a database, contact Stigmem, start a gateway, or write receipts. Run it any time without worrying about side effects. Because those diagnostics read local operator state, the CLI requires an active operator session before it prints the report.

craik doctor --fix still defaults to a dry run. Use --apply for safe supported fixes, and add --yes only when you intend to confirm an unsafe posture change such as rebinding a public gateway config to localhost.

When to run doctor​

First-time setup

Right after craik setup — confirm Craik home, store, and gateway config are valid.

Before going live

Before binding a public gateway, running automation, or making a live provider call.

On a fresh shell

To make sure CRAIK_HOME is pointing where you think it is.

When something feels off

Faster than guessing — every check has a status and an action when one is needed.

Run it​

One command, structured output
craik doctor
Preview supported fixes
craik doctor --fix
Apply safe fixes only
craik doctor --fix --apply

Each check reports a status:

Status
Meaning
What to do
pass
healthy
Nothing to fix.
warning
soft fail
Something is misconfigured or expired but not blocking. Read the action field for guidance.
fail
blocking
Real problem — provider calls will fail, gateway won't start, etc. Fix before proceeding.

The checks​

local_home

Whether the resolved Craik home exists. Run craik home init if missing.

local_store

Whether the SQLite store at state/craik.sqlite exists and is readable.

memory_backend

Whether a shared Stigmem memory backend is configured (and reachable, if env vars are present).

auth_profiles

Whether configured auth profiles can be inspected. No credentials are printed — only structural validity.

auth_profile:<id>

Per-profile credential health: env-var presence, token expiry, and local credential-file readability when applicable.

operator_session

Whether an active operator session exists for commands that inspect local runtime state.

provider_auth

Whether at least one provider auth profile is usable for live provider calls.

model_availability

Whether an active model is configured through the environment or model settings.

gateway_config

Whether a default gateway config is stored. Required before craik setup --enable-gateway can persist a public bind.

gateway_prerequisites

Whether daemon-mode prerequisites are present (ports, binaries, dependencies).

gateway_status

Whether a recent gateway runtime state exists and whether it is running.

channel_pairing

Whether channel identity records exist and at least one external identity is paired.

local_endpoint_safety

Whether provider profile metadata points plaintext HTTP at a non-local endpoint.

secure_credential_store

Whether file-backed auth profile state is owner-only on POSIX systems.

file_permissions

Whether Craik home paths avoid group/world writable permissions.

public_bind_security

Whether gateway configs avoid public binds, or carry explicit policy when public ingress is configured.

stale_sessions_locks

Whether active agent sessions look stale and how many intent locks are recorded.

policy

Whether gateway policy state is inspectable — the envelope is loaded, parsed, and structurally valid.

Reading a profile check​

A healthy profile looks like this:

auth_profile:anthropic:work · pass
{
  "name": "auth_profile:anthropic:work",
  "status": "pass",
  "summary": "Auth profile anthropic:work is ok.",
  "action": null
}

A degraded profile reports a warning without printing the secret value:

auth_profile:anthropic:work · warning
{
  "name": "auth_profile:anthropic:work",
  "status": "warning",
  "summary": "Auth profile anthropic:work is rejected. secret reference could not resolve",
  "action": "Refresh or replace the credential before running live providers."
}

The action field is the human-readable next step. Doctor never tells you "check your env vars" and stops there — it names the profile and tells you what to do.

A practical first-run checklist​

  1. Run setup if you haven't. craik setup creates the local home and default gateway config doctor needs to inspect.

  2. Run craik doctor. Read the output top-to-bottom.

  3. Fix every fail first. Blocking issues prevent the next checks from being meaningful.

  4. Address warnings. Expired tokens, missing env vars, unreachable backends. Use the action field as your script.

  5. Re-run doctor until clean. No noise, no surprises.

Doctor in CI​

craik doctor works headlessly. Pipe it into your favorite log collector or fail your CI job if any check is fail:

Fail CI on any blocking doctor check
craik doctor --json | jq -e 'all(.checks[]; .status != "fail")'

The --json output is stable across releases — the keys are part of the public contract.

craik doctor --fix --dry-run is the automation-friendly preflight for repair planning. It returns a fix.actions[] list with planned, skipped, or requires_confirmation status values and does not write state.

What's next​

DoAuthentication & credentialsAdd, rotate, or replace credential profiles that doctor flagged.DoRun setupIf doctor reported a missing home, run setup first.ReferenceGateway daemon modeThe gateway prerequisites doctor inspects in detail.