Doctor

The doctor command checks your InitRunner environment — API keys, provider SDKs, and service connectivity — in a single command. Pass a PATH, --role, or --flow to validate tools, skills, memory stores, triggers, and MCP servers before you run anything. With --quickstart, it runs a real agent prompt to verify the entire stack end-to-end. With --fix PATH, it also rewrites old envelope YAML to the flat public format.

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 (static checks)
initrunner doctor --role role.yaml
initrunner doctor role.yaml          # same thing via PATH

# Active checks: connect to MCP servers, import custom tools, open memory DBs
initrunner doctor --role role.yaml --deep

# Validate a flow and all its agent roles
initrunner doctor --flow flow.yaml

# Rewrite old envelopes to flat YAML, then repair SDKs / extras
initrunner doctor --fix PATH --yes

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

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.

Telemetry status line

Since v2026.6.2, the config scan prints a usage telemetry status line after the provider tables. It reports whether anonymous usage telemetry is enabled, disabled (with the reason), or off (not yet chosen) when you have not made a choice yet.

Usage telemetry: off (not yet chosen) (anonymous, opt-in; initrunner telemetry status)

This line is advisory and does not affect the exit code. To manage the setting, see Telemetry.

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 rewrites old Agent, Team, and Flow envelopes to flat YAML (spec_version: 3), then detects deprecated YAML fields and offers to patch them in-place. Envelope rewrites write PATH.bak unless you pass --no-backup. Already-flat files and Service/TestSuite documents are skipped. The rewriter refuses when a rewrite would change behavior (for example a Flow whose metadata.name is not kebab-case). See Envelope Migration.

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

--fix --role also installs the extras that role's tools and triggers need, which since v2026.8.9 includes initrunner[mcp] and initrunner[vector]. That is the one-command answer to a role that validates but fails to build on a core install. See Installation.

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

When doctor passes but a real run still fails, raise the log level: initrunner -v run role.yaml -p "ping" shows the provider request and response behind the failure. See Logging.