Skip to main content

​
Overview

The dex doctor command scans entry folders to detect drift, validation errors, and health issues. It can run in interactive mode (TTY) with repair capabilities or in non-interactive mode for CI/CD pipelines.

​
Usage

dex doctor [flags]

​
Modes

​
Interactive Mode (TTY)

When running in a terminal with TTY support:
  • Displays interactive screen with entry health reports
  • Allows filtering and navigation
  • Provides repair functionality for detected issues
  • Shows detailed diagnostics per entry

​
Non-Interactive Mode

When running in non-TTY environment or piped:
  • Prints per-entry report to stdout
  • Exits with non-zero status code if errors are detected
  • Suitable for CI/CD validation gates

​
What Doctor Checks

​
File Structure

  • Presence of entry.json
  • Presence of manifest.json
  • Presence of description.txt
  • Presence of index.html

​
Schema Validation

  • Entry schema compliance
  • Manifest schema compliance
  • Sidebar config validation
  • Format key validation

​
Content Integrity

  • HTML Drift Detection: Compares existing index.html with deterministic regeneration
  • Manifest Normalization: Detects if manifest needs normalization
  • Auth Configuration: Verifies auth trio scripts are present
  • Legacy Code: Flags legacy Auth0 blocks

​
Download Manifest

  • Validates Drive IDs don’t contain URLs or paths
  • Checks for empty buckets
  • Verifies populated download IDs for selected buckets

​
Metadata

  • Tags validation against catalog
  • Sample length presence check
  • Unknown tag detection

​
Interactive TUI Keybindings

  • Up/Down - Select entry report
  • Type to filter slugs
  • Ctrl+S - Repair selected entry
  • Esc - Back to dashboard

​
Repair Functionality

When running in interactive mode, pressing Ctrl+S on a selected entry triggers repair:
  1. Normalizes manifest if needed
  2. Migrates description if missing
  3. Regenerates index.html from canonical template
  4. Updates lifecycle timestamps
  5. Verifies sanitized HTML output

​
Check Indicators

​
Errors (❌)

  • entry.json missing - Critical: entry cannot be processed
  • schema/parse invalid - Entry or manifest fails validation

​
Warnings (⚠)

  • manifest.json missing - Can be repaired with skeleton
  • description.txt missing - Can be migrated from entry.json
  • index.html missing - Can be regenerated
  • STALE HTML - index.html differs from deterministic regeneration
  • auth trio missing - Required auth scripts not found
  • legacy Auth0 blocks - Old auth code still present
  • manifest normalization drift - Manifest needs normalization
  • bucket X has no populated download ids - Empty bucket detected
  • looks like URL/path, expected plain drive id - Invalid Drive ID format
  • unknown tags - Tags not in catalog
  • metadata.sampleLength missing - Missing sample length field

​
Output Example

​
Interactive Mode

┌─ Doctor ─────────────────────────────────────┐
│ Filter: [                                  ] │
│                                              │
│ > tim-feeney                             ✓   │
│   • entry and manifest schema valid          │
│                                              │
│   john-cage                              ✗   │
│   • entry and manifest schema valid          │
│   ⚠ STALE HTML: differs from regen           │
│   ⚠ bucket A has no populated download ids   │
│                                              │
│   pauline-oliveros                       ✓   │
│   • entry and manifest schema valid          │
│                                              │
│ [Ctrl+S: Repair] [Esc: Back]                 │
└──────────────────────────────────────────────┘

​
Non-Interactive Mode

$ dex doctor

✓ tim-feeney
  • entry and manifest schema valid

✗ john-cage
  • entry and manifest schema valid
  ⚠ STALE HTML: index.html differs from deterministic regeneration
  ⚠ bucket A has no populated download ids

✓ pauline-oliveros
  • entry and manifest schema valid

Total: 3 entries, 1 with warnings

​
Exit Codes

  • 0 - All entries healthy
  • 1 - One or more entries have errors

​
Examples

​
Interactive Scan and Repair

dex doctor

​
CI/CD Validation

dex doctor || echo "Health check failed"

​
In Verification Workflow

npm run verify:dex-manual
dex doctor

​
Common Issues and Fixes

​
Stale HTML

Symptom: STALE HTML: differs from deterministic regeneration Fix: Use Ctrl+S in interactive mode to regenerate, or run dex update for the entry

​
Invalid Drive IDs

Symptom: looks like URL/path, expected plain drive id Fix: Edit manifest.json to use plain Drive IDs (e.g., 1aB2cD3eF4gH5) instead of full URLs

​
Missing Files

Symptom: manifest.json missing, description.txt missing, index.html missing Fix: Use repair function (Ctrl+S) to auto-generate missing files

​
Unknown Tags

Symptom: unknown tags: experimental, noise Fix: Either remove tags from entry metadata or add them to the tags catalog

dex init

Create a new entry

dex update

Edit an existing entry

dex entry audit

Runtime and inventory audit

Entry Validation

Production entry validation workflow

​
Notes

  • Doctor scans all subdirectories in ./entries by default
  • Repair is a safe operation that preserves entry data
  • The command uses the canonical template for HTML regeneration
  • Sanitization checks are enforced during repair
  • Doctor is included in preflight checks before deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us