CLI Reference

Note: This document is programmatically generated from the Typer CLI application. Do not edit this file by hand.

Overview

Topological audit and health diagnostics for vector indexes.

Exit Codes

Exit Code	Name	Description
0	OK	Audit completed cleanly; all metrics pass.
1	WARN	Audit completed with warning threshold breaches.
2	FAIL	Audit completed with failure threshold breaches.
3	INCONCLUSIVE	Audit inconclusive (missing capability or sample size).
4	USAGE	Invalid arguments, connection loss, or resource ceiling exceeded.
70	INTERNAL	Unhandled internal engine failure.

Global Options

Option	Type	Default	Description
--verbose, -v	int	0	Raise log verbosity.
--quiet, -q	boolean	False	Only errors to stderr.
--log-format	choice	human	Diagnostic log format (stderr).
--debug	boolean	False	Show tracebacks on internal errors.

Commands

vhecfsck audit

Perform a topological health audit on a vector index target.

Usage

vhecfsck audit [OPTIONS]

Options

Option	Type	Default	Description
--target, -t	str	None	Target index URI or path.
target_pos	str	None	Target index URI or path.
--format	choice	FormatChoice.TEXT	Report output format: text, json, or prometheus.
--output, -o	path	None	Output file path (defaults to stdout).
--queries	int	None	Number of queries to sample.
--queries-count	int	None	Number of queries to sample.
--k	int	None	k nearest neighbors for canary recall.
--hubness-sample	int	None	Sample size for hubness metric.
--k-hub	int	None	k nearest neighbors for hubness.
--hubness-source	str	None	Hubness reference source: 'truth' or 'engine'.
--seed	int	None	Random seed for query sampling.
--nprobe	int	None	IVF nprobe search parameter.
--ef-search	int	None	HNSW ef_search parameter.
--max-seconds	float	None	Maximum wall-clock limit in seconds.
--max-memory-mb	float	None	Maximum memory budget in MB.
--strict-unavailable, --no-strict-unavailable	boolean	None	Treat UNAVAILABLE metrics as FAIL.
--only	str	None	Comma-separated metric IDs to include.
--skip	str	None	Comma-separated metric IDs to skip.
--config	path	None	Path to custom audit configuration file.
--dataset-version	int	None	Dataset version/snapshot to pin for LanceDB.
--column	str	None	Vector column name for multi-vector datasets.
--no-progress	boolean	False	Disable progress reporting to stderr.
--filter	str	None	Restrict canary recall to payload equality (field=value).
--group-by	str	None	Per-group canary breakdown on a payload field.
--baseline	path	None	Path to baseline report JSON file for delta comparison.
--gate	choice	GateChoice.BOTH	Gating policy mode: absolute, delta, or both.

vhecfsck baseline

Capture and manage index baselines.

Usage

vhecfsck baseline [OPTIONS]

Subcommand vhecfsck baseline record

Capture current audit of a target index as a baseline report JSON file.

Option	Type	Default	Description
--target, -t	str	None	Target index URI or path.
target_pos	str	None	Target index URI or path.
--output, -o	path	baseline.json	Output baseline report JSON file path.
--queries	int	None	Number of queries to sample.
--queries-count	int	None	Number of queries to sample.
--k	int	None	k nearest neighbors for canary recall.
--hubness-sample	int	None	Sample size for hubness metric.
--k-hub	int	None	k nearest neighbors for hubness.
--hubness-source	str	None	Hubness reference source ('truth' or 'engine').
--seed	int	None	Random seed for sampling.
--config	path	None	Path to custom audit configuration file.
--no-progress	boolean	False	Disable progress reporting to stderr.

vhecfsck demo

Run a 60-second zero-dependency synthetic index demonstration audit.

Usage

vhecfsck demo [OPTIONS]

Options

Option	Type	Default	Description
--scenario	str	tombstoned	Synthetic scenario name (e.g. tombstoned, healthy, drifted).
--size	choice	DemoSizeChoice.SMALL	Corpus scale size (small, large, or tiny).
--serve	boolean	False	Hand off run to 3D scene visualizer server.
--format	choice	FormatChoice.TEXT	Report output format: text, json, or prometheus.
--output, -o	path	None	Output file path (defaults to stdout).
--no-progress	boolean	False	Disable progress reporting to stderr.

vhecfsck export

Re-render a stored audit report JSON in another format.

Usage

vhecfsck export [OPTIONS]

Options

Option	Type	Default	Description
--report, -r	path	None	Path to input JSON report file.
--format	choice	ExportFormatChoice.TEXT	Report output format: text, json, prometheus, or markdown.
--output, -o	path	None	Output file path (defaults to stdout).

vhecfsck serve

Launch embedded HTTP/WebSocket server for 3D visualizer.

Usage

vhecfsck serve [OPTIONS]

Options

Option	Type	Default	Description
--target, -t	str	``	Target vector index URI.
--port, -p	int	8765	Server HTTP port.
--host	str	127.0.0.1	Bind host address.
--no-browser	boolean	False	Do not automatically open web browser.
--report	path	None	Path to pre-computed JSON report file.