Doctor CLI - PraisonAI

Basic Commands

# Run all fast checks
praisonai doctor

# Show version
praisonai doctor --version

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

Subcommand Reference

Environment Checks

# Check environment configuration
praisonai doctor env

# Show masked API keys
praisonai doctor env --show-keys

# Require specific env vars
praisonai doctor env --require OPENAI_API_KEY,ANTHROPIC_API_KEY

Configuration Checks

# Validate configuration files
praisonai doctor config

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

# Show expected schema
praisonai doctor config --schema

Bot Config Checks

praisonai doctor validates bot.yaml via load_and_validate_bot_yaml against BotYamlSchema for every bot-related check (bot_tokens, bot_config, bot_security, multi_channel_tokens). Common failures and fixes:

Error	Cause	Fix
`Invalid bot.yaml configuration: Unknown channel 'X'. Supported: agentmail, discord, email, slack, telegram, whatsapp`	Channel key is not a recognized platform name (e.g. `telegram_cfo` instead of `telegram`).	Use only platform names as channel keys in bot.yaml, or migrate to gateway.yaml which supports custom keys with `platform:` field.
`No channels configured`	`channels:` block is empty.	Add at least one channel. Re-run `praisonai onboard` to regenerate.
`Invalid mode 'X'`	Unknown transport mode.	Use one of `poll`, `ws`, `webhook`, `hybrid`.

The current BotYamlSchema requires channel keys to be platform names (telegram, discord, etc). For multi-bot setups with custom keys like telegram_cfo, use gateway.yaml instead of bot.yaml — gateway runtime supports custom channel keys with explicit platform: fields. See Gateway Configuration.

Packaging Checks

Diagnose Windows daemon and entry-point issues (python -m praisonai vs the praisonai console script):

# Validate package structure, console script, and metadata
praisonai doctor packaging

# Deeper probes (slower)
praisonai doctor packaging --deep

# Machine-readable output for CI
praisonai doctor packaging --json

Check	What it verifies
Package structure	`__main__.py` exists so `python -m praisonai` works
Console script	`praisonai` is on `PATH` after install
Packaging metadata	Wheel/sdist metadata matches the installed version

Run praisonai doctor packaging on Windows before registering PraisonAI as a scheduled task or NSSM service — misconfigured entry points are the most common cause of “daemon starts but immediately exits”.

Tools Checks

# Check tool availability
praisonai doctor tools

# Filter by category
praisonai doctor tools --category web_search

# Show all tools
praisonai doctor tools --all

# Show only missing tools
praisonai doctor tools --missing-only

Database Checks

# Check database drivers
praisonai doctor db

# Test connectivity (requires --deep)
praisonai doctor db --deep

# Check specific provider
praisonai doctor db --provider postgresql

# Use custom DSN
praisonai doctor db --dsn "postgresql://user:pass@localhost/db"

# Read-only mode (default)
praisonai doctor db --read-only

MCP Checks

# Check MCP configuration
praisonai doctor mcp

# Filter by server name
praisonai doctor mcp --name filesystem

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

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

Observability Checks

# Check observability providers
praisonai doctor obs

# Check specific provider
praisonai doctor obs --provider langfuse

# Test connectivity (requires --deep)
praisonai doctor obs --deep

Skills Checks

# Check skills directories
praisonai doctor skills

# Check specific path
praisonai doctor skills --path ./my-skills

# Detailed requirements diagnostics
praisonai doctor skills --requirements

Sample requirements output:

{
  "total_skills": 5,
  "active": 3,
  "degraded": 1,
  "unavailable": 1,
  "enforcement_level": "warn",
  "sample_issues": [
    "pdf-processor: Missing required tools: pdf_read",
    "email-sender: Missing required environment variables: SMTP_PASSWORD"
  ]
}

Memory Checks

# Check memory storage
praisonai doctor memory

Permissions Checks

# Check filesystem permissions
praisonai doctor permissions

Network Checks

# Check network configuration
praisonai doctor network

# Test DNS and HTTPS (requires --deep)
praisonai doctor network --deep

Performance Checks

# Check import times
praisonai doctor performance

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

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

CI Mode

# Run CI checks (JSON output, strict)
praisonai doctor ci

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

# Custom timeout
praisonai doctor ci --timeout 30

Self-Test

# Run mock self-test (default, 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-mini

# Save test report
praisonai doctor selftest --save-report

Global Flags

# JSON output
praisonai doctor --json
praisonai doctor env --json

# Format selection
praisonai doctor --format json
praisonai doctor --format text

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

# Deep mode (enables network probes, DB connects)
praisonai doctor --deep
praisonai doctor db --deep

# Custom timeout per check
praisonai doctor --timeout 30

# Strict mode (warnings become failures)
praisonai doctor --strict

# Quiet mode (minimal output)
praisonai doctor --quiet

# Disable colors
praisonai doctor --no-color

# Filter checks
praisonai doctor --only python_version,openai_api_key
praisonai doctor --skip network_dns,network_https

Output Examples

Text Output

PraisonAI Doctor v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Python Version: Python 3.11.0 (>= 3.9 required)
✓ PraisonAI Package: praisonai 2.7.0 installed
✓ OpenAI API Key: OPENAI_API_KEY configured (***configured***)
⚠ Virtual Environment: Not running in a virtual environment
✗ Docker: Docker not found
○ ChromaDB: ChromaDB not installed (optional)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6 checks: 3 passed, 1 warnings, 1 failed, 1 skipped
Completed in 15ms

JSON Output

praisonai doctor --json --only python_version

{
  "version": "1.0.0",
  "timestamp": "2025-01-01T00:00:00.000000+00:00",
  "duration_ms": 0.68,
  "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)",
      "metadata": {
        "version": "3.11.0",
        "executable": "/usr/bin/python3"
      },
      "duration_ms": 0.14
    }
  ],
  "summary": {
    "total": 1,
    "passed": 1,
    "warnings": 0,
    "failed": 0,
    "skipped": 0,
    "errors": 0
  },
  "exit_code": 0
}

List Checks Output

praisonai doctor --list-checks

Available Doctor Checks:

  ENVIRONMENT:
    python_version                 Check Python version is 3.9+
    praisonai_package              Check praisonai package is installed
    openai_api_key                 Check OPENAI_API_KEY is configured
    anthropic_api_key              Check ANTHROPIC_API_KEY is configured
    ...

  CONFIG:
    agents_yaml_exists             Check if agents.yaml exists
    agents_yaml_syntax             Validate agents.yaml YAML syntax
    ...

  TOOLS:
    tools_registry                 Check tool registry is accessible
    tools_web_search               Check web search tool availability
    ...

CI/CD Integration

GitHub Actions

- name: Run PraisonAI Doctor
  run: |
    pip install praisonai
    praisonai doctor ci --output doctor-report.json
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

- name: Upload Doctor Report
  uses: actions/upload-artifact@v3
  with:
    name: doctor-report
    path: doctor-report.json

Exit Code Handling

# Check exit code
praisonai doctor
if [ $? -eq 0 ]; then
  echo "All checks passed"
elif [ $? -eq 1 ]; then
  echo "Some checks failed"
elif [ $? -eq 2 ]; then
  echo "Internal error"
fi

Troubleshooting

Common Issues

# Check why a specific check fails
praisonai doctor --only openai_api_key

# Run with verbose output
praisonai doctor env --no-color

# Check network issues
praisonai doctor network --deep

# Verify database connectivity
praisonai doctor db --deep --dsn "$DATABASE_URL"

​Basic Commands

​Subcommand Reference

​Environment Checks

​Configuration Checks

​Bot Config Checks

​Packaging Checks

​Tools Checks

​Database Checks

​MCP Checks

​Observability Checks

​Skills Checks

​Memory Checks

​Permissions Checks

​Network Checks

​Performance Checks

​CI Mode

​Self-Test

​Global Flags

​Output Examples

​Text Output

​JSON Output

​List Checks Output

​CI/CD Integration

​GitHub Actions

​Exit Code Handling

​Troubleshooting

​Common Issues

Basic Commands

Subcommand Reference

Environment Checks

Configuration Checks

Bot Config Checks

Packaging Checks

Tools Checks

Database Checks

MCP Checks

Observability Checks

Skills Checks

Memory Checks

Permissions Checks

Network Checks

Performance Checks

CI Mode

Self-Test

Global Flags

Output Examples

Text Output

JSON Output

List Checks Output

CI/CD Integration

GitHub Actions

Exit Code Handling

Troubleshooting

Common Issues