Skip to content
Bestie

Doctor reference

Doctor is Bestie’s first-class diagnostic command. It explains local setup problems in beginner-friendly language and can repair safe local issues when asked.

Commands

Section titled “Commands”
Terminal window
bestie doctor
bestie doctor --json
bestie doctor --fix
bestie doctor --telegram-connect
bestie doctor --telegram-speech-test

In local development:

Terminal window
bestie doctor
bestie doctor --json
bestie doctor --fix

What Doctor checks

Section titled “What Doctor checks”

Doctor currently checks:

  • Node.js version.
  • Required project files.
  • Runtime paths inside repo-local .bestie/.
  • Config exists and parses.
  • .env exists and is not group/world readable.
  • LLM API key presence without printing the value.
  • LLM timeout sanity.
  • SQLite memory database creation, opening, and schema columns.
  • Character prompt presence.
  • Log directory writability.
  • Existing log file permissions.
  • Telegram token and owner id when Telegram is enabled.
  • Telegram attachment storage size and cleanup guidance.
  • Telegram transcription readiness when enabled.
  • Telegram speech reply readiness when enabled.
  • MCP config summary and missing tool classifications.

bestie doctor --telegram-connect performs an explicit Telegram getMe network check. Default Doctor avoids external Telegram calls.

JSON contract

Section titled “JSON contract”

--json returns a structured report with:

  • checks[] entries containing name, status, message, and optional fix.
  • check statuses: pass, warn, or fail.
  • fixes[] entries containing name, status, and message when --fix is used.
  • fix statuses: fixed, skipped, or failed.
  • issueCount equal to the number of failed checks.
  • no secret-like values.

Exit policy:

  • Exit 0 when issueCount is 0.
  • Exit 1 when failing issues remain.
  • Warnings alone do not make issueCount non-zero.

Safe fixes

Section titled “Safe fixes”

--fix may:

  • Create .bestie/, .bestie/logs/, and .bestie/data/.
  • Initialize or migrate the local SQLite memory database.
  • Restrict existing .env and app log files to owner read/write.
  • Copy legacy .ai-bestie/ to .bestie/ if .bestie/ does not exist, rewriting legacy env/config names from AI_BESTIE_* to BESTIE_*.

--fix does not create or overwrite config files, prompt files, or secrets.

Never silently fixed

Section titled “Never silently fixed”

Doctor must not silently:

  • Overwrite config.
  • Delete data.
  • Change keys.
  • Change webhooks or public channel settings.
  • Stop services.
  • Use sudo.
  • Send test messages externally.

Smoke coverage

Section titled “Smoke coverage”
Terminal window
npm run smoke:doctor
npm run smoke:doctor:json
npm run smoke:doctor:fix
npm run smoke:doctor:exit-code

npm run smoke includes Doctor human output, JSON contract smoke, and safe-fix smoke. The exit-code smoke is separate because it intentionally creates a broken temp runtime and expects Doctor to exit 1.