Doctor

The doctor command checks your InitRunner environment — API keys, provider SDKs, and service connectivity — in a single command. With --quickstart, it runs a real agent prompt to verify the entire stack end-to-end.

Quick Start

# Check provider configuration
initrunner doctor

# Full end-to-end smoke test (makes a real API call)
initrunner doctor --quickstart

# Test a specific role file
initrunner doctor --quickstart --role role.yaml

# Auto-repair detected issues
initrunner doctor --fix

# Auto-fix without prompts (CI-friendly)
initrunner doctor --fix --yes

CLI Options

Config Scan

The config scan runs automatically on every doctor invocation. It checks:

Example output:

               Provider Status
┏━━━━━━━━━━━┳━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Provider  ┃ API Key ┃ SDK ┃ Status         ┃
┡━━━━━━━━━━━╇━━━━━━━━━╇━━━━━╇━━━━━━━━━━━━━━━━┩
│ openai    │ Set     │ OK  │ Ready          │
│ anthropic │ Missing │ —   │ Not configured │
│ google    │ Missing │ —   │ Not configured │
│ groq      │ Missing │ —   │ Not configured │
│ mistral   │ Missing │ —   │ Not configured │
│ cohere    │ Missing │ —   │ Not configured │
│ ollama    │ —       │ —   │ Ready          │
│ docker    │ —       │ —   │ Ready          │
└───────────┴─────────┴─────┴────────────────┘

The scan loads .env files before checking, so keys defined in .env files (project-local or ~/.initrunner/.env) are detected. If --role is provided, the .env in the role's directory is loaded first.

Quickstart Smoke Test

With --quickstart, the doctor runs a real agent prompt after the config scan:

initrunner doctor --quickstart

What it does:

1. Detects the available provider (or uses the one from --role)
2. Builds a minimal agent (or loads the role file if --role is given)
3. Sends a single prompt: "Say hello in one sentence."
4. Reports success or failure with response preview, token count, and duration

On success:

╭───────────────────────────── Quickstart Result ──────────────────────────────╮
│ Smoke test passed!                                                           │
│                                                                              │
│ Response: Hello!                                                             │
│ Tokens: 97 | Duration: 2229ms                                                │
╰──────────────────────────────────────────────────────────────────────────────╯

On failure, the error is displayed and the command exits with code 1:

╭───────────────────────────── Quickstart Result ──────────────────────────────╮
│ Smoke test failed: Model API error: 401 Unauthorized                         │
╰──────────────────────────────────────────────────────────────────────────────╯

Testing a specific role

Use --role to test a specific role file. This loads the role's .env, builds the role's agent (with its model, tools, and system prompt), and runs the smoke prompt against it.

initrunner doctor --quickstart --role examples/roles/code-reviewer.yaml

This is useful for verifying that a role's provider, model, and SDK configuration work before deploying it.

Extended Diagnostics

Since v2026.4.12, doctor can inspect individual roles, run active connectivity checks, and validate entire flows.

Role diagnostics

initrunner doctor --role role.yaml

By default, role diagnostics run static checks only (no network or I/O):

Deep checks

Add --deep to run active checks that hit the network and open databases:

initrunner doctor --role role.yaml --deep

Deep mode adds:

• MCP servers — full connection, tool listing, and latency measurement
• Custom tools — full Python import and function discovery
• Memory store — opens the database to verify it's readable

Flow diagnostics

Validate an entire flow topology and run per-agent diagnostics on every referenced role:

initrunner doctor --flow flow.yaml
initrunner doctor --flow flow.yaml --deep

Dashboard API

The dashboard exposes per-agent diagnostics at:

GET /api/agents/{agent_id}/doctor?deep=false

Auto-fix with deprecation repair

--fix now also detects deprecated YAML fields and offers to patch them in-place. Edits are surgical (they preserve formatting and comments). After fixes are applied, spec_version is auto-bumped if safe.

initrunner doctor --fix --role role.yaml
initrunner doctor --fix --yes   # CI-friendly, no prompts

Use Cases

• First-time setup: Run initrunner doctor after initrunner setup to verify everything is configured.
• CI/CD validation: Add initrunner doctor --quickstart to your CI pipeline to catch provider configuration issues early.
• Debugging: When a role isn't working, doctor quickly shows whether the issue is a missing API key, missing SDK, or unreachable service.
• Multi-provider environments: See at a glance which providers are configured and ready.
• Auto-repair: Run initrunner doctor --fix to resolve missing SDKs, API keys, and config issues. Add --yes for unattended CI repairs.

Exit Codes