# Doctor CLI Reference > Complete reference for `stella doctor` commands ## Commands ### stella doctor Run diagnostic checks. ```bash stella doctor [options] ``` #### Options | Option | Short | Type | Default | Description | |--------|-------|------|---------|-------------| | `--format` | `-f` | enum | `text` | Output format: `text`, `table`, `json`, `markdown` | | `--quick` | `-q` | flag | false | Run only quick checks (tagged `quick`) | | `--full` | | flag | false | Run all checks including slow/intensive | | `--pack` | | string[] | all | Filter by pack name (manifest grouping) | | `--category` | `-c` | string[] | all | Filter by category | | `--plugin` | `-p` | string[] | all | Filter by plugin ID | | `--check` | | string | | Run single check by ID | | `--severity` | `-s` | enum[] | all | Filter output by severity | | `--timeout` | `-t` | duration | 30s | Per-check timeout | | `--parallel` | | int | 4 | Max parallel check execution | | `--no-remediation` | | flag | false | Skip remediation output | | `--verbose` | `-v` | flag | false | Include detailed evidence | #### Categories - `core` - Configuration, runtime, system checks - `database` - Database connectivity, migrations, pools - `service-graph` - Service health, gateway, routing - `security` - Authentication, TLS, secrets - `integration` - SCM, registry integrations - `observability` - Telemetry, logging, metrics #### Examples ```bash # Quick health check stella doctor # Full diagnostic stella doctor --full # Database checks only stella doctor --category database # GitHub integration checks stella doctor --plugin scm.github # Single check stella doctor --check check.database.connectivity # JSON output (for CI/CD) stella doctor --format json # Show only failures and warnings stella doctor --severity fail,warn # Markdown report stella doctor --format markdown > doctor-report.md # Verbose with all evidence stella doctor --verbose # Custom timeout and parallelism stella doctor --timeout 60s --parallel 2 ``` ### stella doctor fix Apply non-destructive fixes from a Doctor report. ```bash stella doctor fix --from report.json [--apply] ``` #### Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `--from` | path | required | Path to JSON report with `how_to_fix` commands | | `--apply` | flag | false | Execute fixes (default is dry-run preview) | Doctor only executes non-destructive commands. If a fix requires a destructive change, it is printed as manual guidance and not executed by Doctor. #### Examples ```bash # Preview fixes (dry-run) stella doctor fix --from doctor-report.json # Apply safe fixes stella doctor fix --from doctor-report.json --apply ``` ### stella doctor export Generate a diagnostic bundle for support. ```bash stella doctor export [options] ``` #### Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `--output` | path | `diagnostic-bundle.zip` | Output file path | | `--include-logs` | flag | false | Include recent log files | | `--log-duration` | duration | `1h` | Duration of logs to include | | `--no-config` | flag | false | Exclude configuration | #### Duration Format Duration values can be specified as: - `30m` - 30 minutes - `1h` - 1 hour - `4h` - 4 hours - `24h` or `1d` - 24 hours #### Examples ```bash # Basic export stella doctor export --output diagnostic.zip # Include logs from last 4 hours stella doctor export --include-logs --log-duration 4h # Without configuration (for privacy) stella doctor export --no-config # Full bundle with logs stella doctor export \ --output support-bundle.zip \ --include-logs \ --log-duration 24h ``` #### Bundle Contents The export creates a ZIP archive containing: ``` diagnostic-bundle.zip +-- README.md # Bundle contents guide +-- doctor-report.json # Full diagnostic report +-- doctor-report.md # Human-readable report +-- environment.json # Environment information +-- system-info.json # System details +-- config-sanitized.json # Configuration (secrets redacted) +-- logs/ # Log files (if --include-logs) +-- stellaops-*.log ``` ### stella doctor list List available checks. ```bash stella doctor list [options] ``` #### Options | Option | Type | Description | |--------|------|-------------| | `--category` | string | Filter by category | | `--plugin` | string | Filter by plugin | | `--format` | enum | Output format: `text`, `json` | #### Examples ```bash # List all checks stella doctor list # List database checks stella doctor list --category database # List as JSON stella doctor list --format json ``` ## Exit Codes | Code | Name | Description | |------|------|-------------| | 0 | `Success` | All checks passed | | 1 | `Warnings` | One or more warnings, no failures | | 2 | `Failures` | One or more checks failed | | 3 | `EngineError` | Doctor engine error | | 4 | `InvalidArgs` | Invalid command arguments | | 5 | `Timeout` | Timeout exceeded | ### Using Exit Codes in Scripts ```bash #!/bin/bash stella doctor --format json > report.json exit_code=$? case $exit_code in 0) echo "All checks passed" ;; 1) echo "Warnings detected - review report" ;; 2) echo "Failures detected - action required" exit 1 ;; *) echo "Doctor error (code: $exit_code)" exit 1 ;; esac ``` ## CI/CD Integration ### GitHub Actions ```yaml - name: Run Stella Doctor run: | stella doctor --format json --severity fail,warn > doctor-report.json exit_code=$? if [ $exit_code -eq 2 ]; then echo "::error::Doctor checks failed" cat doctor-report.json exit 1 fi ``` ### GitLab CI ```yaml doctor: stage: validate script: - stella doctor --format json > doctor-report.json artifacts: when: always paths: - doctor-report.json allow_failure: exit_codes: - 1 # Allow warnings ``` ### Jenkins ```groovy stage('Health Check') { steps { script { def result = sh( script: 'stella doctor --format json', returnStatus: true ) if (result == 2) { error "Doctor checks failed" } } } } ``` ## Output Formats ### Text Format (Default) Human-readable console output with colors and formatting. ``` Stella Ops Doctor ================= Running 47 checks across 8 plugins... [PASS] check.config.required All required configuration values are present [FAIL] check.database.migrations.pending Diagnosis: 3 pending migrations in schema 'auth' Fix Steps: # Apply migrations stella system migrations-run --module Authority -------------------------------------------------------------------------------- Summary: 46 passed, 0 warnings, 1 failed (47 total) Duration: 8.3s -------------------------------------------------------------------------------- ``` ### JSON Format Machine-readable format for automation: ```json { "summary": { "total": 47, "passed": 46, "warnings": 0, "failures": 1, "skipped": 0, "duration": "PT8.3S" }, "executedAt": "2026-01-12T14:30:00Z", "checks": [ { "checkId": "check.config.required", "pluginId": "stellaops.doctor.core", "category": "Core", "severity": "Pass", "diagnosis": "All required configuration values are present", "evidence": { "description": "Configuration validated", "data": { "configSource": "appsettings.json", "keysChecked": "42" } }, "duration": "PT0.012S" }, { "checkId": "check.database.migrations.pending", "pluginId": "stellaops.doctor.database", "category": "Database", "severity": "Fail", "diagnosis": "3 pending migrations in schema 'auth'", "evidence": { "description": "Migration status", "data": { "schema": "auth", "pendingCount": "3" } }, "remediation": { "steps": [ { "order": 1, "description": "Apply pending migrations", "command": "stella system migrations-run --module Authority", "commandType": "Shell" } ] }, "duration": "PT0.234S" } ] } ``` ### Markdown Format Formatted for documentation and reports: ```markdown # Stella Ops Doctor Report **Generated:** 2026-01-12T14:30:00Z **Duration:** 8.3s ## Summary | Status | Count | |--------|-------| | Passed | 46 | | Warnings | 0 | | Failures | 1 | | Skipped | 0 | | **Total** | **47** | ## Failed Checks ### check.database.migrations.pending **Status:** FAIL **Plugin:** stellaops.doctor.database **Category:** Database **Diagnosis:** 3 pending migrations in schema 'auth' **Evidence:** - Schema: auth - Pending count: 3 **Fix Steps:** 1. Apply pending migrations ```bash stella system migrations-run --module Authority ``` ## Passed Checks - check.config.required - check.database.connectivity - ... (44 more) ``` ## Environment Variables | Variable | Description | |----------|-------------| | `STELLAOPS_DOCTOR_TIMEOUT` | Default per-check timeout | | `STELLAOPS_DOCTOR_PARALLEL` | Default parallelism | | `STELLAOPS_CONFIG_PATH` | Configuration file path | ## See Also - [Doctor Overview](./README.md) - [Doctor Capabilities Specification](./doctor-capabilities.md)