> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Doctor CLI > CLI reference for PraisonAI Doctor health checks ## Basic Commands ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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`. 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](/docs/features/gateway-config-migration). ### Gateway Doctor Checks Run individual gateway checks: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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. | ### Environment Deep Check — Optional Dependencies ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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): ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "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](/docs/features/doctor-optional-deps) 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): ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check observability providers praisonai doctor obs # Check specific provider praisonai doctor obs --provider langfuse # Test connectivity (requires --deep) praisonai doctor obs --deep ``` ### Skills Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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:** ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "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. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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](/docs/features/doctor-runtime-migration) for the full guide. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 | ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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](/docs/features/doctor-runtime-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](/docs/features/runtime-preflight) for the full guide. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check Docker installation and configuration praisonai doctor docker # Deep probes praisonai doctor docker --deep # JSON output praisonai doctor docker --json ``` ### LLM Provider Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check metadata store configuration praisonai doctor metadata-store --json ``` ### Memory Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check memory storage praisonai doctor memory ``` ### Permissions Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check filesystem permissions praisonai doctor permissions ``` ### Network Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Check network configuration praisonai doctor network # Test DNS and HTTPS (requires --deep) praisonai doctor network --deep ``` ### Performance Checks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ``` 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai doctor --json --only python_version ``` ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} - 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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: ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} $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`.