stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
d7be6ba34be1f39699adf954a164faeff09db8de
git.stella-ops.org/docs/doctor/cli-reference.md
master d7be6ba34b audit, advisories and doctors/setup work
2026-01-13 18:53:39 +02:00

9.3 KiB
Raw Blame History

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, 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

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

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

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

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)