Koko Koala Logo
Koko
0
CLI

Diagnostics (koko doctor)

Diagnostics & Architecture Integrity

The `koko doctor` command is the built-in introspection and drift-control engine of Koko CLI. As codebases grow and engineering teams add dependencies, environment flags, and background services, original architectural conventions often suffer from silent configuration drift.

✓ Sub-millisecond Execution: `koko doctor` audits your workspace directory tree, package managers, and container ports in under 20ms.
✓ Active Drift Prevention: Verifies real file configurations against the single source of truth in `koko.config.json` and the Master Catalog.
✓ Non-destructive Self-Healing: The `--fix` flag reconciles discrepancies and updates manifests automatically without breaking custom business logic.

Command Syntax & Flags Reference

Syntax: `koko doctor [flags]`

All supported options for local developer audits and automated CI/CD quality gates:

  • -f, --fix - Automatically apply detected fixes and update koko.config.json.
  • -d, --dir <path> - Target project directory to analyze (default: current directory .).
  • -v, --verbose - Output verbose validation traces for all packages and configs.
  • --json - Output machine-readable JSON summary for CI/CD pipelines and webhooks.
Terminal
# Standard interactive audit koko doctor # Diagnose and auto-repair workspace drift koko doctor --fix # Analyze specific subdirectory with verbose trace koko doctor --dir ./apps/web --verbose # JSON output for CI/CD status checks koko doctor --json

The 5 Diagnostic Health Pillars

During execution, `koko doctor` runs five core diagnostic verifications across your codebase:

✓ 1. Manifest Schema Validation: Validates that `koko.config.json` exists at the workspace root and strictly conforms to official JSON Schema specifications.
✓ 2. Monorepo & Workspaces Mapping: For Turborepo and pnpm monorepos, verifies that `apps/*` and `packages/*` cross-links and TypeScript path aliases resolve cleanly.
✓ 3. Dependency Catalog Drift: Compares installed package versions in `package.json`, `go.mod`, or `requirements.txt` against the Master Catalog to prevent outdated or vulnerable libraries.
✓ 4. Docker Database Port Health: Probes database container ports declared in `docker-compose.yml` (PostgreSQL 5432, MongoDB 27017, MySQL 3306) to warn about host port collisions.
✓ 5. Linter & Tooling Alignment: Checks that TypeScript (`tsconfig.json`), ESLint, Prettier, or Biome configurations adhere to recommended best practices.

Self-Healing Mode (--fix)

Running `koko doctor --fix` executes a transactional reconciliation routine in four distinct phases:

1. In-Memory Virtual Staging: Evaluates required adjustments inside the Virtual File System (VFS) before writing to disk.

2. Manifest Re-alignment: Updates `koko.config.json` registering any untracked addons or modules.

3. Script Reconciliation: Restores missing root development scripts (`dev`, `build`, `lint`) in `package.json`.

4. Summary Benchmark: Reports all applied patches with execution time in milliseconds.

Terminal
$ koko doctor --fix [✓] koko.config.json schema: OK [✓] Monorepo workspace mapping: OK [!] Dependency Drift: @auth/core version out of sync -> Applying fix: updated koko.config.json to v2.0.0 catalog standard [✓] Docker container ports: No conflicts detected ✓ Diagnostics passed. 1 auto-fix applied successfully in 18ms.

CI/CD Pipeline Integration (GitHub Actions)

Integrate `koko doctor` as an automated gatekeeper in your GitHub Actions workflows to ensure pull requests maintain architectural consistency:

Terminal
name: Architecture Integrity Check on: push: branches: [main] pull_request: branches: [main] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: 20 - name: Install Koko CLI run: npm install -g koko-app - name: Run Koko Doctor Audit run: koko doctor
← Previous Commands & Flags CLI Next → Cross-Validation Safety Rules CLI