CLI

Installed with the package as the ingestlib command (uv run ingestlib …; python -m ingestlib is equivalent). ingestlib --version prints the installed version.

Command	Purpose
init	scaffold config.yaml (+ .env)
doctor	verify the configured stack with real calls
ingest	index files or folders
sync	reconcile a folder with the corpus
list	show every stored document
remove	erase a document (by path or doc_id)
backfill	rebuild the vector store from stored artifacts
search	cited retrieval from the shell
mcp	serve the corpus to agents over MCP (needs ingestlib[mcp])

init and doctor set up and verify a stack; the rest manage the documents in it — the corpus-management guide is Manage a corpus. Every corpus command takes --namespace.

ingestlib init

Writes the setup files into the current directory — where config discovery looks.

uv run ingestlib init [--local] [--force]

Flag	Effect
(none)	Default stack: Bedrock + sqlite + Jina. Writes config.yaml (with an aws: section to fill) and .env (with key slots).
--local	Zero-cloud stack: Ollama + sqlite + local artifacts + no reranker. Writes config.yaml only — no keys are needed, so no .env.
--force	Overwrite existing files. Without it, init refuses and exits 1 if config.yaml or .env already exists.

Output ends with the preset's next steps (models to pull, keys to fill, the OCR server command, and ingestlib doctor).

ingestlib doctor

Verifies the configured stack with real calls — a chat round-trip, an actual embedding, a store reachability probe. Checks only what your config.yaml choices require.

uv run ingestlib doctor

Check	Failure mode
Python version	fail below 3.12
Config discovery + parse	fail — and doctor stops; nothing else can run
LibreOffice	warn — DOCX/PPTX need it; PDF/images don't
OCR server	warn — parse/ingest need it; classify/split/extract/retrieve don't
LLM provider	fail — real chat call
Embedding provider	fail — real embedding; prints the dimension
Reranker	fail (skip when reranker: none)
Artifact store	fail — S3 credentials + bucket, or local-folder writability
Vector store	fail — liveness probe; never creates indexes or schema

Marks: ✓ ok · ! warning · ✗ failure · - skipped.

Exit code 0 when nothing failed (warnings allowed), 1 otherwise — safe to gate a deployment script on.

Every failure line carries the same one-sentence fix the library raises at runtime — the troubleshooting catalog lists them all.

Costs

Doctor's LLM and reranker probes are real calls: fractions of a cent on cloud providers, free on Ollama. Local checks (config, LibreOffice, sqlite, folders) are free.

ingestlib ingest

Index one or more files or folders. A folder expands to its ingestible files (PDF/DOCX/PPTX/PNG/JPEG/WebP, recursive).

ingestlib ingest report.pdf
ingestlib ingest docs/ contracts/ invoice.pdf   # mix files and folders
ingestlib ingest report.pdf --namespace tenant-a

Prints a per-stage progress line and the outcome per file (ingested, replaced, moved, or skipped — see Manage a corpus). Exit 1 if any file failed; the rest still process.

ingestlib sync

Reconcile a folder with the corpus: new files ingest, edited files replace, renamed files move, and — with --prune — deleted files are removed.

ingestlib sync corpus/                     # ingest/replace/move
ingestlib sync corpus/ --dry-run           # print the plan, change nothing
ingestlib sync corpus/ --prune             # also delete gone files
ingestlib sync corpus/ --prune --dry-run   # preview the prune first

Flag	Effect
--prune	delete documents whose file is gone (root-scoped; refuses on an empty scan)
--dry-run	print the plan, execute nothing
--namespace	reconcile one partition

Always --dry-run before a first --prune. Guardrails are detailed in Pruning safely. Exit 1 if any file errored.

ingestlib list

The registry as a table — doc_id (short), pages, chunks, category, namespace, source path.

ingestlib list
ingestlib list --namespace tenant-a        # one partition (default: all)

ingestlib remove

Erase one document from both stores (vectors, then artifacts).

ingestlib remove report.pdf                # by source path
ingestlib remove 7b6b95d79149              # by doc_id (full or a unique prefix)

Exit 1 when the target matches nothing (or a prefix is ambiguous) — nothing is deleted.

ingestlib backfill

Rebuild the vector store from stored split artifacts — no re-parse. For a provider switch, a new store connector, or a wiped index (see backfill).

ingestlib backfill
ingestlib backfill --namespace tenant-a

ingestlib search

Cited retrieval from the shell — the ingest→verify loop without a Python session.

ingestlib search "what were the risks?"
ingestlib search "revenue growth" --top-k 10
ingestlib search "invoice INV-20114" --no-rerank

Prints ranked hits with score, citation, heading, and a snippet.

ingestlib mcp

Serve the corpus to MCP agents (Claude Desktop, Cursor, …) as tools — search, extract, ingest, sync, remove, backfill, classify, list_documents, doctor. Needs the extra: pip install "ingestlib[mcp]". Full guide: Serve to agents (MCP).

ingestlib mcp                                   # stdio (local clients)
ingestlib mcp --transport http --port 8000      # remote; needs MCP_TOKEN
ingestlib mcp --read-only                       # only the read tools

Flag	Effect
--transport	stdio (default, local) or http (streamable, remote)
--host	http bind address (default 127.0.0.1)
--port	http port (default 8000)
--read-only	hide the write tools (ingest/remove/sync/backfill)

The http transport requires MCP_TOKEN in .env (bearer auth) and binds localhost unless you pass --host. stdio needs no token.