Skip to main content
The praisonai doctor command provides comprehensive health checks and diagnostics for your PraisonAI installation, configuration, and environment.

Quick Start

# Run all fast checks
praisonai doctor

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

# Output in JSON format
praisonai doctor --json

# CI mode with deterministic output
praisonai doctor ci

Subcommands

SubcommandDescription
envCheck environment variables and system configuration
configValidate configuration files (agents.yaml, workflow.yaml)
toolsCheck tool availability and dependencies
dbCheck database drivers and connectivity
mcpCheck MCP server configuration
obsCheck observability providers (Langfuse, LangSmith, etc.)
skillsCheck agent skills directories
memoryCheck memory storage and sessions
permissionsCheck filesystem permissions
networkCheck network connectivity and proxy settings
performanceCheck import times and module counts
ciCI-optimized checks with JSON output
selftestTest agent creation and chat functionality

Global Flags

FlagDescription
--jsonOutput in JSON format
--format text|jsonOutput format (default: text)
--output PATHWrite report to file
--deepEnable deeper probes (DB connects, network checks)
--timeout SECPer-check timeout in seconds (default: 10)
--strictTreat warnings as failures
--quietMinimal output
--no-colorDisable ANSI colors
--only IDSOnly run these check IDs (comma-separated)
--skip IDSSkip these check IDs (comma-separated)
--list-checksList available check IDs
--versionShow doctor module version

Exit Codes

Root Command

CodeMeaning
0All checks passed
1One or more checks failed (or warnings in strict mode)
2Internal error

CI Mode

CodeMeaning
0All checks passed
1One or more checks failed
2Timeout
3Internal error

Examples

Environment Checks

# Check all environment settings
praisonai doctor env

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

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

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

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

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
    }
  ],
  "summary": {
    "total": 50,
    "passed": 45,
    "warnings": 3,
    "failed": 1,
    "skipped": 1,
    "errors": 0
  },
  "exit_code": 1
}

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)

Configuration (config)

  • agents.yaml existence and syntax
  • workflow.yaml validation
  • .praison config directory
  • .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

Memory (memory)

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

Permissions (permissions)

  • ~/.praison directory
  • Project .praison directory
  • 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

Self-Test (selftest)

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