Doctor

Comprehensive health checks and diagnostics for PraisonAI

Before you run your first Agent(...), run praisonai doctor --live to make sure your keys and dependencies are in order. The praisonai doctor command provides comprehensive health checks and diagnostics for your PraisonAI installation, configuration, and environment.

Quick Start

# Full setup report (multi-category — first-run / troubleshooting)
praisonai doctor

# Fast env-only checks (CI-friendly)
praisonai doctor --quick        # alias for `praisonai doctor env`
praisonai doctor env

# Run checks for a specific category
praisonai doctor config
praisonai doctor tools

# Output in JSON format
praisonai doctor --json

# CI mode with deterministic output
praisonai doctor ci

Full Setup Report

Running praisonai doctor with no subcommand runs the full multi-category setup report — the recommended first-run and troubleshooting path.

# Live check — pings providers with your API keys
praisonai doctor --live

# Deep + strict for release gates
praisonai doctor --deep --strict --json

Subcommands

Global Flags

Exit Codes

Root Command

CI Mode

Full Setup Report

Running praisonai doctor without a subcommand runs a comprehensive report combining environment, config, tools, and provider checks for first-run and operator troubleshooting.

# Full setup report
praisonai doctor

# Include live provider pings
praisonai doctor --live

# Machine-readable output
praisonai doctor --json

# Treat warnings as failures (useful for strict operator checks)
praisonai doctor --strict

When warnings or failures are found, a “Next steps:” footer lists numbered remediations:

─────────────────────────────
Next steps:
  1. ⚠ Optional Dependencies: Reinstall the broken optional package(s): chromadb (Knowledge/RAG features)
  2. ✗ OpenAI API key: Set OPENAI_API_KEY in your environment or ~/.praisonai/.env

doctor fix Auto-Remediation

praisonai doctor fix runs safe auto-remediation for common setup issues.

# Dry-run: list proposed changes without modifying anything (default)
praisonai doctor fix

# Apply safe fixes (creates .bak backup alongside the original file)
praisonai doctor fix --execute

# Apply without creating a backup
praisonai doctor fix --execute --no-backup

# Target a specific YAML file
praisonai doctor fix --file agents.yaml

# Minimal output
praisonai doctor fix --quiet

Phase-1 scope: migrate deprecated cli_backend YAML configuration to the new models.default.runtime format.

Examples

Environment Checks

# Check all environment settings
praisonai doctor env

# Check with API key visibility
praisonai doctor env --show-keys

Optional Dependencies (deep mode)

# Probe all eight optional packages in parallel
praisonai doctor env --deep

# Machine-readable output for CI
praisonai doctor env --deep --json

--deep enables the optional_deps check, which probes eight optional packages on daemon threads and reports each as available, missing, broken, or slow. A broken package (installed but failing to import) surfaces as WARN with a remediation message; missing and slow packages do not fail the check.

Configuration Validation

# Validate all config files
praisonai doctor config

# Validate specific file
praisonai doctor config --file agents.yaml

# Show expected schema
praisonai doctor config --schema

Database Checks

# Check database drivers
praisonai doctor db

# Test database connectivity (deep mode)
praisonai doctor db --deep

# Check specific provider
praisonai doctor db --provider postgresql

MCP Server Checks

# Check MCP configuration
praisonai doctor mcp

# List MCP tools
praisonai doctor mcp --list-tools

# Test server spawning (deep mode)
praisonai doctor mcp --deep

Skills Diagnostics

# Check skills health
praisonai doctor skills

# Detailed requirements diagnostics
praisonai doctor skills --requirements

# Deep skill validation
praisonai doctor skills --deep

Performance Analysis

# Check import times
praisonai doctor performance

# Set import time budget
praisonai doctor performance --budget-ms 1000

# Show top slow imports
praisonai doctor performance --top 20

Self-Test

# Run mock self-test (no API calls)
praisonai doctor selftest --mock

# Run live self-test with API calls
praisonai doctor selftest --live

# Use specific model
praisonai doctor selftest --live --model gpt-4o

Runtime Preflight

Validate multi-agent team YAML for runtime compatibility before AgentTeam.start(). No LLM calls or API keys required. See Runtime Preflight for the capability matrix and check IDs.

# Preflight team YAML
praisonai doctor runtime --team agents.yaml

# JSON output for CI
praisonai doctor runtime --team team.yaml --json

# Deep mode (flag accepted; runtime checks do not branch on it today)
praisonai doctor runtime --team config.yaml --deep

Runtime Migration

Detect and migrate legacy cli_backend fields to the new models.default.runtime format. See Runtime Config Migration for full details.

# Scan for legacy configuration
praisonai doctor runtime

# Preview what would change (dry-run)
praisonai doctor runtime --fix

# Apply migration with backup
praisonai doctor runtime --fix --execute

# Target a specific file
praisonai doctor runtime --fix --execute --file ./teams/agents.yaml

Auto-Remediation (doctor fix)

praisonai doctor fix runs safe auto-remediation for common setup issues — dry-run by default, no changes without --execute.

Phase-1 scope: migrating deprecated cli_backend YAML configuration. This does not yet fix all possible issues.

• Dry-run by default; --execute applies changes.
• A .bak backup is created on --execute unless --no-backup.
• --file/-f targets a specific YAML; otherwise searches cwd.
• --quiet/-q suppresses non-essential output.

# Preview what would change (default)
praisonai doctor fix

# Apply safe fixes with .bak backup
praisonai doctor fix --execute

# Apply without creating .bak files
praisonai doctor fix --execute --no-backup

# Target a specific file
praisonai doctor fix --file ./teams/agents.yaml

See also: Runtime Config Migration — describes the cli_backend→runtime mapping that fix currently automates.

Docker Checks

# Check Docker installation and configuration
praisonai doctor docker

# Deep probes
praisonai doctor docker --deep

# JSON output
praisonai doctor docker --json

LLM Provider Checks

# Check LLM providers configuration
praisonai doctor llm-providers

# Deep probes
praisonai doctor llm-providers --deep

# JSON output
praisonai doctor llm-providers --json

Memory Store Checks

# Check memory store backends
praisonai doctor memory-store

# Deep probes
praisonai doctor memory-store --deep

# JSON output
praisonai doctor memory-store --json

Metadata Store Checks

# Check metadata store configuration
praisonai doctor metadata-store --json

CI Integration

# Run CI checks with JSON output
praisonai doctor ci

# Fail fast on first error
praisonai doctor ci --fail-fast

# Save report to file
praisonai doctor ci --output report.json

Filtering Checks

# List all available checks
praisonai doctor --list-checks

# Run only specific checks
praisonai doctor --only python_version,openai_api_key

# Skip specific checks
praisonai doctor --skip network_dns,network_https

# Combine filters
praisonai doctor env --only openai_api_key,anthropic_api_key

Status Symbols

The text formatter automatically picks symbols that match your terminal encoding.

Use --json for machine-readable output that does not depend on terminal encoding.

JSON Output Format

{
  "version": "1.0.0",
  "timestamp": "2025-01-01T00:00:00.000000+00:00",
  "duration_ms": 150.5,
  "environment": {
    "python_version": "3.11.0",
    "os_name": "Darwin",
    "praisonai_version": "2.7.0"
  },
  "results": [
    {
      "id": "python_version",
      "title": "Python Version",
      "category": "environment",
      "status": "pass",
      "message": "Python 3.11.0 (>= 3.9 required)",
      "duration_ms": 0.5
    },
    {
      "id": "optional_deps",
      "title": "Optional Dependencies",
      "category": "environment",
      "status": "warn",
      "message": "5 available, 2 missing, 1 slow/skipped (chromadb)",
      "metadata": {
        "slow": ["chromadb"],
        "missing": ["crawl4ai", "praisonaiagents-embeddings"]
      }
    }
  ],
  "summary": {
    "total": 50,
    "passed": 45,
    "warnings": 3,
    "failed": 1,
    "skipped": 1,
    "errors": 0
  },
  "exit_code": 1
}

Optional Dependencies

praisonai doctor probes optional packages in parallel on daemon threads, one per package, with a per-package timeout.

Packages probed:

• chromadb — Knowledge/RAG features
• crawl4ai — Web crawling
• duckduckgo_search — Web search
• praisonaiagents — Core agents
• litellm — LLM providers
• openai — OpenAI provider
• anthropic — Anthropic provider
• mem0 — Memory features

Each package falls into one of four outcome buckets:

When any package is broken, the check reports WARN with the remediation message:

Reinstall the broken optional package(s): {names}

Check Categories

Environment (env)

• Python version validation
• Package installation checks
• API key configuration
• OS and architecture info
• Virtual environment detection
• Binary availability (git, docker, npx)
• Optional dependencies deep probe (--deep) — runs concurrently with a per-package timeout; slow imports are reported as slow/skipped instead of blocking the full check.

Configuration (config)

• agents.yaml existence and syntax — the framework: field is validated against the adapter registry, so any installed adapter (built-in or third-party entry-point plugin) passes the check
• workflow.yaml validation
• Project config directory — canonical .praisonai/ first, with a legacy .praison/ read-only fallback
• .env file detection

Tools (tools)

• Tool registry access
• Web search tools
• File operation tools
• Code execution tools
• API key requirements

Database (db)

• Driver availability (PostgreSQL, SQLite, Redis, MongoDB)
• ChromaDB for RAG
• Connection testing (deep mode)

MCP (mcp)

• Configuration file validation
• npx availability
• Python MCP package
• Server configuration validation
• Server spawn testing (deep mode)

Observability (obs)

• Langfuse configuration
• LangSmith configuration
• AgentOps configuration
• PraisonAI telemetry

Skills (skills)

• Skills directory discovery
• SKILL.md validation
• PraisonAI skills module
• Capability requirements (active/degraded/unavailable counts, enforcement level)

Memory (memory)

• Memory directories
• JSON file integrity
• Session storage
• ChromaDB vector memory

Permissions (permissions)

• ~/.praison directory (legacy home fallback — intentionally not migrated in PR #4946)
• Project .praison directory (legacy fallback — intentionally not migrated in PR #4946)
• Temp directory
• Current working directory
• Config directory

Network (network)

• DNS resolution (deep mode)
• HTTPS connectivity (deep mode)
• Proxy configuration
• SSL/TLS settings
• OpenAI base URL

Performance (performance)

• Package import times
• Slow import detection (deep mode)
• Loaded module count

performance_praisonai_import skips with reason “Install full wrapper: pip install praisonai” when pip install praisonai-code is used without the praisonai wrapper (PR #2851).

Packaging (packaging)

• praisonai_package_structure — validates the praisonai wrapper’s __main__.py entry point
• console_script_execution — runs praisonai --version
• python_module_execution — runs python -m {praisonai|praisonai_code} --version (retargets on standalone)

praisonai_package_structure and console_script_execution skip with reason “Install full wrapper: pip install praisonai” when pip install praisonai-code is used without the praisonai wrapper (PR #2851). python_module_execution does not skip — it retargets to python -m praisonai_code --version on standalone.

Self-Test (selftest)

• Agent import
• Agent instantiation
• LLM configuration
• Mock/live chat testing
• Tools wiring

Runtime (runtime)

• Team YAML runtime compatibility (--team)
• Handoff and capability validation across agents
• Mixed-runtime warnings
• Legacy cli_backend migration (--fix, --execute) — also reachable via top-level praisonai doctor fix
• Workflow YAML placeholder (--workflow — returns SKIP)

Skips with reason “Install full wrapper: pip install praisonai” when pip install praisonai-code is used without the praisonai wrapper.

Serve & Endpoints (serve)

• Serve module availability
• Endpoints module availability
• Endpoints CLI handler
• Server connectivity (deep mode)
• Discovery endpoint (deep mode)
• A2U module availability
• Provider adapters availability
• FastAPI availability
• Uvicorn availability

Skips with reason “Install full wrapper: pip install praisonai” when pip install praisonai-code is used without the praisonai wrapper.

Bots (bots)

• Bot token environment variables (bot_tokens)
• Bot.yaml configuration file validation (bot_config) †
• Bot security configuration checks (bot_security) †
• Multi-channel token configuration validation (multi_channel_tokens) † — MEDIUM
• Gateway config validation (gateway_config_validation) † — HIGH
• Gateway security settings (gateway_security) † — HIGH
• Gateway config migration (gateway_config_migration) † — MEDIUM
• Gateway environment variables (gateway_env_substitution) — MEDIUM
• Gateway shell readiness (gateway_shell_readiness) † — HIGH
• Gateway channel probe (gateway_channel_probe) † — HIGH, deep-only (--deep)
• Gateway duplicate services (gateway_duplicate_services) † — HIGH, deep-only (--deep)
• Gateway recent inbound (gateway_no_inbound_recent) † — MEDIUM, deep-only (--deep)

Skips with reason "Install full wrapper: pip install praisonai" when pip install praisonai-code is used without the praisonai wrapper.

ACP

• acp_module — ACP module import (praisonai.acp)
• ACP server reachability
• ACP protocol handshake validation
• Agent Client Protocol configuration

Skips with reason “Install full wrapper: pip install praisonai” when pip install praisonai-code is used without the praisonai wrapper.

Multi-Channel Token Check Details

The multi_channel_tokens check validates your multi-channel bot setup:

Category: BOTS

Severity: MEDIUM

PASS Conditions:

• Each channel uses a unique environment variable
• Each environment variable resolves to a unique token value
• Follows `PLATFORM_

_BOT_TOKEN` naming convention

WARN Conditions:

• Environment variable doesn’t follow naming convention
• Environment variable is unset but referenced in config

FAIL Conditions:

• Two channels point to the same environment variable
• Two environment variables resolve to the same token value

Skip Condition:

• bot.yaml missing → check is skipped

Sample Remediation Messages:

• “Each channel must have a unique bot token. Create separate bots in @BotFather and use unique environment variables.”
• “Consider following the naming convention PLATFORM_ROLE_BOT_TOKEN for clarity.”

Gateway Config Validation (gateway_config_validation)

Severity: HIGH

praisonai doctor --only gateway_config_validation

Gateway Security (gateway_security)

Severity: HIGH

As of PR #6046, the empty-restrictions verdict mirrors the resolved unknown_user_policy: allow fails, deny (default) warns, pair passes.

praisonai doctor --only gateway_security

Gateway Config Migration (gateway_config_migration)

Severity: MEDIUM

praisonai doctor --only gateway_config_migration

See Gateway Config Migration for before/after examples.

Gateway Environment Variables (gateway_env_substitution)

Severity: MEDIUM

praisonai doctor --only gateway_env_substitution

Gateway Shell Readiness (gateway_shell_readiness)

Severity: HIGH

Offline validation of allow_shell / auto_approve_shell / approval wiring per channel — no LLM or network calls. Auto-discovers config from --file, then gateway.yaml, then bot.yaml.

The check builds each shell-enabled channel through the same enable_shell_tools() path the gateway uses, so an exposed/multi-user channel that would be downgraded surfaces as a WARN — matching the gateway’s runtime WARN when auto_approve_shell: true is set on a 0.0.0.0 bind or a channel with a group_policy without auto_approve_shell_acknowledge_exposed: true. See Bot Shell Execution → Exposure-aware auto-approval.

praisonai doctor --only gateway_shell_readiness
praisonai doctor bots --file /path/to/bot.yaml

Gateway Channel Probe (gateway_channel_probe)

Severity: HIGH · Deep-only (requires_deep=True)

Live per-channel credential probe (auth.test / getMe / identify). Runs only under praisonai doctor --deep or praisonai doctor bots --deep.

praisonai doctor bots --deep --only gateway_channel_probe
praisonai doctor --deep --only gateway_channel_probe

Gateway Duplicate Services (gateway_duplicate_services)

Severity: HIGH · Deep-only (requires_deep=True)

Scans for competing gateway services and shared Slack tokens — the same scan behind praisonai gateway test --check-duplicates. Inspects macOS LaunchAgents (ai.praison.bot, ai.hermes.gateway), both .env files, and Hermes runtime state. Runs only under praisonai doctor --deep.

Remediation: “Compare SLACK_APP_TOKEN across services; stop duplicate gateways before messaging Slack.” See Duplicates tier.

praisonai doctor --deep --only gateway_duplicate_services

Gateway Recent Inbound (gateway_no_inbound_recent)

Severity: MEDIUM · Deep-only (requires_deep=True)

Scans the gateway log for recent @mention received: markers (last 10 minutes) — the same check behind praisonai gateway test --check-inbound. Runs only under praisonai doctor --deep.

Remediation: “Send a Slack @mention to your bot, then run: praisonai gateway test –config <cfg> –check-inbound –since 5m.” See Inbound tier.

praisonai doctor --deep --only gateway_no_inbound_recent