Skip to content

Diagnostic CLI: bun run diagnose prints a full pre-flight #6

@jstuart0

Description

@jstuart0

Goal

A single command that tells an operator — in 30 seconds — whether their AgentPulse instance is healthy. Think `kubectl cluster-info dump` but for AgentPulse: what the config looks like, which LLM providers can reach their upstreams, whether Telegram is connected, whether the DB is healthy, etc.

Useful for support ("paste me the output of `bun run diagnose`") and self-service debugging.

Scope

  • New file `scripts/diagnose.ts` + `"diagnose": "bun scripts/diagnose.ts"` in package.json.
  • Checks (each printed with green ✓ / amber ! / red ✗):
    1. Config — DATABASE_URL, DISABLE_AUTH, AGENTPULSE_AI_ENABLED, AGENTPULSE_SECRETS_KEY present.
    2. DB — connect, run a `SELECT 1`, print row counts for sessions / events / api_keys.
    3. Active supervisors — how many registered, last heartbeat age.
    4. LLM providers — for each configured provider, attempt `GET /v1/models` (or Anthropic `/v1/models`) and report reachability + model count.
    5. Notification channels — Telegram credential status, webhook vs. polling state, last-poll age.
    6. AI watcher — queue depth, running runs, stuck sessions.
  • Print a one-line summary at the bottom: `AgentPulse OK` or `AgentPulse has N issues — see above`.

Acceptance criteria

  • `bun run diagnose` exits 0 on a healthy instance, 1 on any failing check.
  • No mutations — read-only against the live DB + upstreams.
  • Documented in the wiki's Operations page.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions