git.stella-ops.org/docs/doctor/cli-reference.md

Doctor CLI Reference

Complete reference for stella doctor commands

Commands

stella doctor

Run diagnostic checks.

stella doctor [options]

Options

Option	Short	Type	Default	Description
--format	-f	enum	text	Output format: text, json, markdown
--quick	-q	flag	false	Run only quick checks (tagged quick)
--full		flag	false	Run all checks including slow/intensive
--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

# 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 export

Generate a diagnostic bundle for support.

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

# 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.

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

# 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

#!/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

- 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

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

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:

{
  "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:

# 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)