mdvdb logo mdvdb
Markdown source

mdvdb doctor

Run a read-only health check for the current project. doctor reports configuration discovery, embedding connectivity, index integrity, source discovery, frontmatter Relations, and Shard/Topic configuration in one result.

Usage

mdvdb doctor [OPTIONS]

Options

This command has no command-specific options. It accepts the global options, including --root, --json, --verbose, and --no-color.

Diagnostic checks

A successful diagnostic run returns nine checks in this order:

#CheckWhat it validates
1Config loadedShows the resolved embedding provider, model, and dimensions. The command has already loaded configuration when this check is emitted.
2User configLooks for ~/.mdvdb/config.yaml, or config.yaml below MDVDB_CONFIG_HOME. A missing user config is a warning because it is optional.
3Project configChecks that the project has a .markdownvdb/ directory.
4API keyExplicitly validates OPENAI_API_KEY for the OpenAI provider. Mock needs no key; other providers are reported as configured and are actually exercised by the connectivity check.
5Provider reachableSends one test embedding request with a five-second timeout. Authentication, endpoint, model, and network failures surface here.
6IndexReports documents, chunks, edge vectors, and vectors. A healthy index has vectors = chunks + edges. An empty or mismatched index warns.
7Source directoriesDiscovers Markdown in the configured source directories and reports the file count.
8RelationsWarns about dangling frontmatter Relation targets, schema target folders with no indexed files, and unquoted [[wikilink]] values that YAML parsed as nested lists.
9ShardsValidates Shard definitions, target folders, and local Topic definitions. Missing or malformed configuration warns.

Each check is Pass, Warn, or Fail. Warnings describe repairable or optional conditions; failures normally prevent an operation such as source discovery or provider access from working.

Human-readable output

  ● mdvdb doctor

  ✓ Config loaded             OpenAI / text-embedding-3-small / 1536
  ✓ User config               /home/user/.mdvdb/config.yaml
  ✓ Project config            .markdownvdb/
  ✓ API key                   OPENAI_API_KEY is set
  ✓ Provider reachable        OK (243ms)
  ✓ Index                     57 docs, 342 chunks, 360 vectors (342 chunk + 18 edge)
  ✓ Source directories        ./ (57 .md files)
  ✓ Relations                 18 relation link(s), all targets resolve
  ✓ Shards                    3 Shard(s) configured, all folders exist

  9/9 checks passed

Warnings are included in the denominator but not the passed count:

  ! Index                     empty — run `mdvdb ingest` to index your markdown files
  ! Relations                 2 dangling relation(s): projects/a.md#owner → people/missing.md, +1 more
  ! Shards                    2 Shard(s) configured; 1 missing folder(s): archive (archive)

Examples

# Run all checks in the current project
mdvdb doctor

# Return the structured result
mdvdb doctor --json

# Diagnose another project
mdvdb doctor --root /path/to/project

# Include diagnostic logging
mdvdb doctor -v

JSON output

--json serializes a DoctorResult. The checks array uses the same order and detail strings as the human-readable result.

{
  "checks": [
    {
      "name": "Config loaded",
      "status": "Pass",
      "detail": "OpenAI / text-embedding-3-small / 1536"
    },
    {
      "name": "User config",
      "status": "Pass",
      "detail": "/home/user/.mdvdb/config.yaml"
    },
    {
      "name": "Project config",
      "status": "Pass",
      "detail": ".markdownvdb/"
    },
    {
      "name": "API key",
      "status": "Pass",
      "detail": "OPENAI_API_KEY is set"
    },
    {
      "name": "Provider reachable",
      "status": "Pass",
      "detail": "OK (243ms)"
    },
    {
      "name": "Index",
      "status": "Pass",
      "detail": "57 docs, 342 chunks, 360 vectors (342 chunk + 18 edge)"
    },
    {
      "name": "Source directories",
      "status": "Pass",
      "detail": "./ (57 .md files)"
    },
    {
      "name": "Relations",
      "status": "Pass",
      "detail": "18 relation link(s), all targets resolve"
    },
    {
      "name": "Shards",
      "status": "Pass",
      "detail": "3 Shard(s) configured, all folders exist"
    }
  ],
  "passed": 9,
  "total": 9
}
FieldTypeDescription
checksDoctorCheck[]Ordered diagnostic results.
passednumberNumber of checks with status Pass.
totalnumberNumber of checks returned.
checks[].namestringHuman-readable check name.
checks[].status"Pass" | "Fail" | "Warn"Check status.
checks[].detailstringContext or repair information.

Troubleshooting

CheckSymptomWhat to do
Project config.markdownvdb not foundRun mdvdb init.
API keyOPENAI_API_KEY not setConfigure the credential via the shell, .markdownvdb/.env, or mdvdb config secret set OPENAI_API_KEY --stdin.
Provider reachableTimeout or authentication/model errorCheck the endpoint, model, credentials, and network. For Ollama, verify the service is running.
IndexEmptyRun mdvdb ingest.
IndexVector mismatchRebuild with mdvdb ingest --reindex. The expected count is chunks plus edge vectors, not chunks alone.
Source directoriesDiscovery failureCheck configured paths and read permissions.
RelationsDangling targetCorrect the link target or add/index the target file. Quote wikilink values in YAML, for example owner: "[[people/ada]]".
RelationsSchema target matches no fileCorrect the Relation field’s target folder or index that folder.
ShardsMissing folder or malformed TopicCorrect the Shard path or its local Topic definition, then rerun doctor.

Notes

  • The index is opened read-only; doctor does not rebuild or mutate it.
  • The provider check makes one real embedding request and may consume a small amount of provider quota.
  • The OpenAI credential has a dedicated preflight check. For other providers, rely on the provider connectivity result for credential validation.