notify doctors work, audit work, new product advisory sprints
This commit is contained in:
master
396
docs/doctor/cli-reference.md
Normal file
396
docs/doctor/cli-reference.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# 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`, `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
|
||||
|
||||
```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 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)
|
||||
Reference in New Issue
Block a user