Doctor - Complete API Reference
Run system diagnostics, check health status, and troubleshoot issues.
Chat Commands
Health Checks
/doctor Run all diagnostics /doctor quick Quick health check /doctor full Full diagnostic scan /doctor <component> Check specific component
Component Checks
/doctor system OS, memory, disk /doctor node Node.js version, memory /doctor network Connectivity tests /doctor api API key validation /doctor database Database connection /doctor channels Channel health
Status
/health Quick health status /status System status overview /status verbose Detailed status
TypeScript API Reference
Create Doctor Service
import { createDoctorService } from 'clodds/doctor';
const doctor = createDoctorService({ // Checks to run checks: ['system', 'node', 'network', 'api', 'database', 'channels'],
// Thresholds thresholds: { memoryWarning: 80, // % memory usage memoryCritical: 95, diskWarning: 80, // % disk usage diskCritical: 95, latencyWarning: 1000, // ms latencyCritical: 5000, },
// Timeout timeoutMs: 30000, });
Run Diagnostics
// Run all checks const report = await doctor.runDiagnostics();
console.log(Overall: ${report.status}); // 'healthy' | 'degraded' | 'unhealthy'
console.log(Checks passed: ${report.passed}/${report.total});
for (const check of report.checks) {
const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '⚠' : '✗';
console.log(${icon} ${check.name}: ${check.message});
if (check.details) {
console.log( ${JSON.stringify(check.details)});
}
}
Run Specific Check
// Check system resources const system = await doctor.checkSystem();
console.log(OS: ${system.os} ${system.version});
console.log(CPU: ${system.cpuUsage}%);
console.log(Memory: ${system.memoryUsage}% (${system.memoryUsedGB}/${system.memoryTotalGB} GB));
console.log(Disk: ${system.diskUsage}% (${system.diskUsedGB}/${system.diskTotalGB} GB));
Check Node.js
const node = await doctor.checkNode();
console.log(Node.js: ${node.version});
console.log(Heap: ${node.heapUsed}/${node.heapTotal} MB);
console.log(RSS: ${node.rss} MB);
console.log(Uptime: ${node.uptime} seconds);
Check Network
const network = await doctor.checkNetwork();
console.log(Internet: ${network.internet ? 'Connected' : 'Disconnected'});
console.log(DNS: ${network.dns ? 'Working' : 'Failed'});
for (const [endpoint, result] of Object.entries(network.endpoints)) {
console.log(${endpoint}: ${result.reachable ? 'OK' : 'Failed'} (${result.latencyMs}ms));
}
Check API Keys
const api = await doctor.checkApiKeys();
for (const [provider, status] of Object.entries(api)) {
console.log(${provider}: ${status.valid ? 'Valid' : 'Invalid'});
if (status.error) {
console.log( Error: ${status.error});
}
if (status.quota) {
console.log( Quota: ${status.quota.used}/${status.quota.limit});
}
}
Check Database
const db = await doctor.checkDatabase();
console.log(Connected: ${db.connected});
console.log(Latency: ${db.latencyMs}ms);
console.log(Version: ${db.version});
console.log(Tables: ${db.tables});
console.log(Size: ${db.sizeMB} MB);
Check Channels
const channels = await doctor.checkChannels();
for (const channel of channels) {
console.log(${channel.name}: ${channel.status});
if (channel.error) {
console.log( Error: ${channel.error});
}
console.log( Connected: ${channel.connected});
console.log( Last message: ${channel.lastMessage});
}
Format Report
// Get formatted report const report = await doctor.runDiagnostics(); const formatted = doctor.formatReport(report);
console.log(formatted); // Outputs nicely formatted diagnostic report
Diagnostic Checks
Check What it Tests
system OS, CPU, memory, disk
node Node.js version, heap, memory
network Internet, DNS, API endpoints
api API key validity and quotas
database Connection, latency, schema
channels Channel connections, health
mcp MCP server connections
dependencies npm packages, versions
Status Levels
Status Meaning
healthy All checks pass
degraded Some warnings, still functional
unhealthy Critical failures, action needed
Check Results
Result Meaning
pass Check succeeded
warn Warning threshold exceeded
fail Critical failure
skip Check skipped (not applicable)
CLI Commands
Run all diagnostics
clodds doctor
Quick check
clodds doctor --quick
Check specific component
clodds doctor --check system
JSON output
clodds doctor --json
Common Issues
High Memory Usage
⚠ Memory: 85% used
Solution: Restart the service or increase available memory
API Key Invalid
✗ Anthropic API: Invalid key
Solution: Check ANTHROPIC_API_KEY in .env
Database Connection Failed
✗ Database: Connection refused
Solution: Check DATABASE_URL and ensure PostgreSQL is running
Channel Disconnected
⚠ Telegram: Disconnected
Solution: Check TELEGRAM_BOT_TOKEN and network connectivity
Best Practices
-
Run regularly — Check health daily or after changes
-
Monitor trends — Watch for gradual degradation
-
Set alerts — Alert on unhealthy status
-
Fix warnings — Don't wait for failures
-
Review before deploy — Run doctor before production changes