Doctor CLI - PraisonAI

Basic Commands

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

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

# Show version
praisonai doctor --version

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

# Preview auto-fix for common setup issues (dry-run, no files changed)
praisonai doctor fix

# Apply auto-fix and write changes
praisonai doctor fix --execute

Full-Report Root Flags

Running praisonai doctor with no subcommand runs the full multi-category setup report.

Flag	Effect
`--quick`	Fast env-only path (alias for `praisonai doctor env`)
`--live`	Include live provider pings — validates API keys, not just presence
`--deep`	Enable deeper probes across all categories
`--strict`	Treat warnings as failures (affects exit code)
`--json`	Machine-readable output for CI

When the report contains warnings or failures, praisonai doctor prints a numbered “Next steps:” section listing the recommended remediation for each issue. Hidden when no issues exist, and suppressed under --quiet.

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

# Deep probe optional deps — parallel with per-package timeout
praisonai doctor env --deep

# Custom overall timeout (per-package timeout scales as timeout/4)
praisonai doctor env --deep --timeout 20

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 and gateway.yaml via load_and_validate_gateway_yaml against the unified GatewayConfigSchema (BotYamlSchema is an alias). Common failures and fixes:

Error	Cause	Fix
`Invalid gateway/bot configuration: Unknown channel 'X'`	Channel platform not recognised.	Use a supported platform: `telegram`, `discord`, `slack`, `whatsapp`, `email`, `agentmail`, `linear`, `webhook`. Custom channel keys require an explicit `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`.
`Environment variable 'X' not set`	`${VAR}` in config is unresolved.	Export the variable or add it to `~/.praisonai/.env`. Run `praisonai doctor --only gateway_env_substitution`.

Single-bot (platform + token), multi-channel (agents + channels), and BotOS (platforms:) YAML shapes all validate against the same schema. See Gateway Config Migration.

Gateway Doctor Checks

Run individual gateway checks:

praisonai doctor --only gateway_config_validation,gateway_security
praisonai doctor --only gateway_config_migration
praisonai doctor --only gateway_env_substitution

Check ID	Severity	What it verifies
`gateway_config_validation`	HIGH	Config file validates against `GatewayConfigSchema`.
`gateway_security`	HIGH	User restrictions, tokens, and `GATEWAY_AUTH_TOKEN`.
`gateway_config_migration`	MEDIUM	Legacy format migration opportunities.
`gateway_env_substitution`	MEDIUM	All `${VAR}` references resolve.

Config version check

praisonai gateway doctor also inspects the config_version stamp in gateway.yaml. When the stamp is missing or stale, it reports drift and points at --fix:

config: out of date (config_version unstamped -> 1); run 'gateway doctor --fix'

In --json output this sets config_version to "out-of-date". A stamp newer than this build supports — or a malformed one (true, "1", 1.0) — is refused, never migrated: config_version becomes "unsupported" and config_version_error carries the message. Doctor never downgrades a config a newer build wrote. praisonai gateway doctor --fix migrates an out-of-date gateway.yaml forward: it applies the safe config migrations, stamps config_version, and rewrites the file atomically (tmpfile + fsync + os.replace), so an interrupted --fix cannot truncate the file. This is in addition to the existing weak-gateway.auth_token repair. --fix --dry-run previews with config: would … lines and writes nothing. See Gateway Config Migration › Doctor-driven migration.

Extending gateway doctor

Tool and channel packages can register their own checks via the praisonai.health_checks entry point, and they run alongside the built-ins. See Extensible Gateway Doctor for the plugin author guide.

Third-party checks appear next to the built-ins in --list-checks and JSON output.
--fix also runs plugin repairs, with the same --dry-run preview behaviour.
The loopback weak-token warning is routed to stderr, so --json stdout stays a single parseable JSON document.
--json output carries a top-level health block (checksRun / repaired / validated / results).
The exit code is 1 whenever any residual error finding remains — built-in or plugin.

Environment Deep Check — Optional Dependencies

# Probe optional packages in parallel (requires --deep)
praisonai doctor env --deep

# JSON output for CI gating
praisonai doctor env --deep --json

Expected output shape (available / missing / broken / slow buckets):

{
  "id": "optional_deps",
  "status": "WARN",
  "message": "5 optional packages available, 2 not installed, 1 broken",
  "details": "Missing: gradio (Gradio UI), tavily (Tavily search); Broken install: chromadb (Knowledge/RAG features)",
  "remediation": "Reinstall the broken optional package(s): chromadb (Knowledge/RAG features)",
  "metadata": {
    "available": ["mem0ai", "litellm", "praisonaiui", "crawl4ai", "duckduckgo_search"],
    "missing":   ["gradio (Gradio UI)", "tavily (Tavily search)"],
    "broken":    ["chromadb (Knowledge/RAG features)"],
    "slow":      []
  }
}

See Optional Dependencies Check for the full four-bucket table, per-package timeout formula, and CI gating examples.

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"
  ]
}

Auto-Remediation (`doctor fix`)

doctor fix runs safe auto-remediation for common setup issues. Phase-1 scope: migrate deprecated cli_backend YAML configuration.

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

# Apply safe fixes (creates .bak backup)
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

Flag	Default	Purpose
`--dry-run / --execute`	`--dry-run`	Preview vs. apply fixes
`--no-backup`	`False`	Skip `.bak` backup when applying
`--file, -f TEXT`	auto-detect in cwd	Config file to target
`--quiet, -q`	`False`	Minimal output

--execute modifies files on disk. A .bak backup is created alongside the original unless --no-backup is passed.

Runtime Migration Checks

Detect and migrate legacy cli_backend YAML fields to models.default.runtime. See Runtime Config Migration for the full guide.

# Scan for legacy configuration (no changes made)
praisonai doctor runtime

# Preview changes (dry-run, default when --fix is set)
praisonai doctor runtime --fix

# Apply changes with timestamped backup
praisonai doctor runtime --fix --execute

# Check a specific file
praisonai doctor runtime --file agents.yaml

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

# JSON output
praisonai doctor runtime --json

# Deep probes
praisonai doctor runtime --deep

Flag	Default	Purpose
`--file, -f TEXT`	auto-detect in cwd	Config file to check
`--fix`	`False`	Enable migration mode
`--dry-run / --execute`	`--dry-run`	Preview vs apply
`--team TEXT`	—	Team YAML file to validate
`--workflow TEXT`	—	Workflow YAML file to validate (placeholder — returns SKIP)
`--json`	`False`	JSON output
`--deep`	`False`	Enable deeper probes

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.

Flag	Default	Purpose
`--dry-run / --execute`	`--dry-run`	Preview vs apply
`--no-backup`	`False`	Skip `.bak` creation on execute
`--file, -f TEXT`	auto-detect in cwd	Specific config file to fix
`--quiet, -q`	`False`	Minimal 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.

Runtime Preflight Checks

Validate team YAML for runtime compatibility, handoffs, and installed frameworks without LLM calls. See Runtime Preflight for the full guide.

# Basic team validation
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

# Workflow placeholder (returns SKIP — not yet implemented)
praisonai doctor runtime --workflow workflow.yaml

Flag	Purpose
`--team TEXT`	Team YAML file to validate
`--workflow TEXT`	Workflow YAML file (placeholder)
`--json`	Machine-readable output for CI
`--deep`	Enable deeper probes

Exit codes: 0 — no issues; 1 — issues detected or team file missing; 2 — internal error.

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

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

Status Symbols

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

Status	UTF-8 terminals	Non-UTF-8 terminals (e.g. Windows cp1252)
Pass	`✓`	`[OK]`
Warn	`⚠`	`[!]`
Fail	`✗`	`[X]`
Skip	`○`	`[-]`
Error	`✗`	`[X]`

Detection runs once when the formatter starts. UTF-8 terminals always use the Unicode symbols. Anything else (Windows default consoles, legacy cp1252/cp437, etc.) automatically falls back to ASCII so praisonai doctor never crashes with UnicodeEncodeError.

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

Output Examples

Text Output

UTF-8 terminals
Windows cp1252

PraisonAI Doctor v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Python Version: Python 3.11.0 (>= 3.9 required)
✓ 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)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5 checks: 2 passed, 1 warnings, 1 failed, 1 skipped
Completed in 15ms

PraisonAI Doctor v1.0.0
----------------------------------------------------------------------
[OK] Python Version: Python 3.13.2 (>= 3.9 required)
[OK] OpenAI API Key: OPENAI_API_KEY configured (***configured***)
[!]  Virtual Environment: Not running in a virtual environment
[X]  Docker: Docker not found
[-]  ChromaDB: ChromaDB not installed (optional)
----------------------------------------------------------------------
5 checks: 2 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"

Windows Unicode / encoding errors

As of v4.x, praisonai doctor auto-detects your terminal encoding and falls back to ASCII status symbols ([OK] [!] [X] [-]) on non-UTF-8 consoles, so the historical UnicodeEncodeError: 'charmap' codec crash on Windows cmd.exe / PowerShell no longer happens. If you prefer Unicode output on Windows, run one of:

$env:PYTHONIOENCODING="utf-8"
praisonai doctor env

Or use Windows Terminal / a UTF-8 capable shell. For machine-readable output that does not depend on terminal encoding, use --json.

​Basic Commands

​Full-Report Root Flags

​Subcommand Reference

​Environment Checks

​Configuration Checks

​Bot Config Checks

​Gateway Doctor Checks

​Config version check

​Extending gateway doctor

​Environment Deep Check — Optional Dependencies

​Packaging Checks

​Tools Checks

​Database Checks

​MCP Checks

​Observability Checks

​Skills Checks

​Auto-Remediation (doctor fix)

​Runtime Migration Checks

​Auto-Remediation (doctor fix)

​Runtime Preflight Checks

​Docker Checks

​LLM Provider Checks

​Memory Store Checks

​Metadata Store Checks

​Memory Checks

​Permissions Checks

​Network Checks

​Performance Checks

​CI Mode

​Self-Test

​Global Flags

​Status Symbols

​Output Examples

​Text Output

​JSON Output

​List Checks Output

​CI/CD Integration

​GitHub Actions

​Exit Code Handling

​Troubleshooting

​Common Issues

​Windows Unicode / encoding errors

Basic Commands

Full-Report Root Flags

Subcommand Reference

Environment Checks

Configuration Checks

Bot Config Checks

Gateway Doctor Checks

Config version check

Extending gateway doctor

Environment Deep Check — Optional Dependencies

Packaging Checks

Tools Checks

Database Checks

MCP Checks

Observability Checks

Skills Checks

Auto-Remediation (`doctor fix`)

Runtime Migration Checks

Auto-Remediation (`doctor fix`)

Runtime Preflight Checks

Docker Checks

LLM Provider Checks

Memory Store Checks

Metadata Store Checks

Memory Checks

Permissions Checks

Network Checks

Performance Checks

CI Mode

Self-Test

Global Flags

Status Symbols

Output Examples

Text Output

JSON Output

List Checks Output

CI/CD Integration

GitHub Actions

Exit Code Handling

Troubleshooting

Common Issues

Windows Unicode / encoding errors