Crate fathomdb_cli 

FathomDB operator CLI — the fathomdb binary: parser plus verb runtime.

Installing this crate gives you the fathomdb command. It is operator-only and deliberately ships no application query surface: there is no fathomdb search / get / list. Use one of the SDKs (the fathomdb facade crate for Rust, or the Python / TypeScript packages) to read and write data.

Two roots:

• fathomdb doctor <verb> — read-only or artifact-producing diagnostics: check-integrity, safe-export, verify-embedder, trace, dump-schema, dump-row-counts, dump-profile, dump-mutations, orphan-provenance, warm-cache, recompute-mean.
• fathomdb recover --accept-data-loss <flag> — the only lossy, non-bit-preserving root: --truncate-wal, --rebuild-vec0, --rebuild-projections, --excise-source, and the --excise-collection / --excise-record-key pair.

--json is the normative machine-readable contract on every verb; exit codes are a stable class set (0 clean, 64 data-loss acknowledged, 65 findings, 66 artifact failure, 70 unrecoverable, 71 lock-held).

The CLI is not required for deletion on request. Since 0.8.20 the SDKs ship purge and erase_source themselves. recover --excise-source remains the only route into the engine’s reserved _-prefixed provenance namespace, and --excise-collection / --excise-record-key has no SDK peer.

This crate enables the operator cargo feature on the fathomdb facade, which is what un-gates the recovery seam it drives.

Surface owned by dev/interfaces/cli.md; verb semantics by dev/design/recovery.md. Each verb invokes the corresponding fathomdb::Engine method and serializes the typed report under a per-verb JSON discriminator.

Modules

exit_code

Stable exit-code classes for the operator CLI.

Structs

CheckIntegrityArgs

Per-verb argument set for doctor check-integrity.

Cli

Top-level CLI invocation.

DoctorArgs

Wrapper carrying the doctor verb table beneath the doctor root.

DumpMutationsArgs

Slice 34 — argument set for doctor dump-mutations <collection> [--after-id <n>] [--limit <n>] [--json] <db_path>. A read-only operator diagnostic that pages the op-store mutation log over the existing Engine::read_mutations seam.

RecoverArgs

Argument set for the recover root command.

SafeExportArgs

Per-verb argument set for doctor safe-export.

SimpleDoctorArgs

Shared args for doctor verbs whose only options are --json and a required <db_path> positional. cli.md § Output posture: --json is the normative machine-readable contract on every verb.

TraceArgs

Per-verb argument set for doctor trace.

VerifyEmbedderArgs

Per-verb argument set for doctor verify-embedder. cli.md (amended 2026-05-15) locks the invocation as verify-embedder --identity <s> --dimension <n> <db_path>.

WarmCacheArgs

EU-5b — fathomdb doctor warm-cache argument set.

Enums

CliOutcome

Outcome classes that map to the stable exit-code matrix in dev/interfaces/cli.md § Exit-code classes.

Command

Root command verbs.

DoctorCommand

Doctor verb table per dev/interfaces/cli.md § Doctor verbs.

Functions

effective_dump_limit

Resolve the effective doctor dump-mutations page limit: the operator’s --limit (or the default when omitted), clamped to the engine page cap [DUMP_MUTATIONS_MAX_LIMIT]. Pure + total so the clamp is unit-pinned without seeding a >1M-row log (tests/parser.rs).

engine_error_to_outcome

Map an EngineError to the CliOutcome class per dev/interfaces/cli.md § Error to exit-code mapping.

engine_open_error_to_outcome

Map an EngineOpenError to the CliOutcome class per dev/interfaces/cli.md § Error to exit-code mapping.

outcome_to_exit_code

Map an outcome to the stable exit code defined in cli.md.

run

Run a parsed CLI command.