Command-Line Interface

The vectlite console script ships with the Python package. After pip install vectlite, it is available as vectlite or via python -m vectlite.

Commands at a glance

Command	Purpose
vectlite stats <path>	Dimension, metric, record counts, file sizes, active indexes.
vectlite count <path>	Filtered or namespace-scoped count.
vectlite list <path>	List records as JSON.
vectlite dump <path>	Export every record as JSONL via cursor pagination.
vectlite search <path>	Run a dense search and print results.
vectlite compact <path>	Fold the WAL into the snapshot and persist ANN sidecars.
vectlite verify <path>	Check WAL + snapshot integrity.
vectlite bench <path>	Search benchmark with QPS and latency.
vectlite import-jsonl <path> <file>	Bulk import from a JSONL file.
vectlite import-csv <path> <file>	Bulk import from a CSV file.

Inspecting a database

# Database overview
vectlite stats my.vdb

# Count records, optionally scoped
vectlite count my.vdb --namespace blog
vectlite count my.vdb --filter '{"source": "blog"}'

# List the first 10 records
vectlite list my.vdb --limit 10 --filter '{"source": "blog"}'

# Stream every record as JSONL (uses cursor pagination)
vectlite dump my.vdb > backup.jsonl

Searching

vectlite search my.vdb --query '[1.0, 0.0, 0.5]' --k 5

The --query value is a JSON array of floats matching the database dimension.

Bulk import

Each line of the JSONL file should be a record dict (same shape as Record in the Python API):

{"id": "doc1", "vector": [0.1, 0.2, ...], "metadata": {"source": "blog"}}
{"id": "doc2", "vector": [0.3, 0.4, ...], "metadata": {"source": "docs"}}

vectlite import-jsonl my.vdb data.jsonl --dimension 384

CSV imports need a column containing the vector (as a JSON-encoded list or comma-separated floats):

vectlite import-csv my.vdb data.csv --dimension 384 --vector-col embedding

Maintenance

# Fold the WAL into the snapshot and persist ANN sidecars
vectlite compact my.vdb

# Verify WAL + snapshot integrity
vectlite verify my.vdb

Run compact periodically when using TTL or after large batch writes.

Benchmarking

vectlite bench my.vdb --queries 1000 --k 10

Reports QPS and p50/p95/p99 latency over the requested number of randomly-sampled queries. Useful to compare quantization settings or measure the impact of payload indexes.

Scripting tips

• dump + import-jsonl is the simplest roundtrip for backups, migrations, or copying a database between machines.
• Combine with jq to filter / transform records: vectlite dump my.vdb | jq 'select(.metadata.source == "blog")' > blogs.jsonl.
• vectlite stats exits with a non-zero code on corruption — useful in healthchecks.