doctor

What It Does

doctor runs a multi-check diagnosis across git setup, RAGit structure, config, embedding contract state, embedding cache health, zvec runtime, schema layout, manifest consistency, and the current security posture.

When To Use / When Not To Use

When to use it

A command is failing and you need a structured diagnostic view.
You suspect a store, schema, or manifest mismatch.
You want a CI-friendly health check that can exit non-zero on failure.

When not to use it

You only want a quick current-state summary. Use status.
You already know the issue and need to reindex. Use ingest.

Syntax

pnpm ragit doctor [--format text|json|both] [--cwd <path>]

Arguments And Options

--format text|json|both: Choose human text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

There is no positional input and no JSON payload input.
JSON output includes checks and hasFailure.
If any check fails, the process exits with a non-zero code after printing the result.
Embedding-oriented check names include embedding.credentials, embedding.deprecated-fields, embedding.contract, embedding.migration-needed, embedding.cache-dir, and embedding.cache-namespace.
Security-oriented check names include security.masking-config, security.output-remasking, security.remote-egress, security.quarantine-dir, security.legacy-control-plane, and security.legacy-store.

Examples

Human terminal flow:

pnpm ragit doctor

Agent-oriented flow:

pnpm ragit doctor --format json

Failures And Cautions

A failing doctor result often signals repository or runtime setup problems outside a single command.
Use the individual check names in the JSON output when automating follow-up actions.
embedding.cache-dir validates that the configured cache directory stays inside the repository and is writable.
embedding.cache-namespace validates that the active namespace manifest is readable, or that no namespace has been materialized yet.

doctor

On this page