426 lines
9.3 KiB
Markdown
426 lines
9.3 KiB
Markdown
# 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)
|