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

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.

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.

Exit Codes