Reference

CLI, configuration and security details for v1.5.2. On an installed system use docubrowser; from a cloned repo use ./docubrowser.py.

Command-line interface

docubrowser <command> [options]

Command	Description
`start` / `stop` / `restart`	Control the search server (`start` runs the Ollama check first)
`status`	Server status, document, embedding and tag counts
`scan [TYPE ...]`	Scan, index and embed documents. `--no-embed` skips embedding
`rescan [TYPE ...]`	Alias for `scan`
`scan-file --file PATH`	Index a single file, then embed it
`embed`	Generate embeddings for un-embedded documents
`open`	Open the UI in your default browser
`purge`	Scan the index for PII and remove matching documents
`ignore add\|remove\|list DIR`	Manage excluded directories (auto-purges on add)
`report`	File-type breakdown, no DB changes
`scan-missing [--dry-run]`	Remove rows for genuinely missing files; leaves unmounted paths alone
`stopall`	Stop all scans, embeds and the server
`duplist` / `dupclean`	List duplicates / interactively review and remove them

Global options

--db PATH      SQLite database path (overrides config)
--port PORT    Server port (overrides config)
--config FILE  Config file path

Examples

docubrowser start --port 9000
docubrowser scan pdf txt              # only PDFs and plain text
docubrowser scan --limit 100          # first 100 unindexed files
docubrowser scan --workers 4          # 4 extraction workers
docubrowser scan-file --file /path/to/document.pdf
docubrowser purge --dry-run           # preview PII matches (safe)
docubrowser ignore add ~/Documents/myWorkDocs
docubrowser duplist --near-dups --threshold 0.95
docubrowser scan-missing --dry-run

Type filters for scan: pdf, txt, md, html; the default is all supported types.

scan-file is for retrying problem files: it removes the file from scan_blacklist.txt, refuses files in pii_blacklist.txt, and routes scanned PDFs to ocr_list_pdfs.txt.

Configuration

DocuBrowse reads the first config file it finds: /etc/docubrowse.config, then ./docubrowse.config next to docubrowser.py.

# docubrowse.config
doc_dir      = ~/Documents
db_path      = /home/user/DocuBrowse/du-docs.db
port         = 8643
work_dir     = /home/user/DocuBrowse
lang         = en

Key	Default
`doc_dir`	None. Must be configured via Settings or the config file
`db_path`	`<script dir>/du-docs.db`
`port`	`8643`
`work_dir`	`<script dir>`
`lang`	`en` (also `ja`, `ko`, `zh`, `zh-hant`)

Environment variables

Environment variables override matching config keys. CLI flags still win.

Variable	Description
`DOCUBROWSE_DOC_DIR`	Primary document directory
`DOCUBROWSE_DB` / `DOCUBROWSE_DB_PATH`	Path to `du-docs.db`
`DOCUBROWSE_PORT`	HTTP port (default 8643)
`DOCUBROWSE_WORK_DIR`	Working directory for runtime data
`OLLAMA_HOST`	Ollama base URL (default `http://localhost:11434`); also `DOCUBROWSE_OLLAMA_HOST`

Architecture

docubrowser.py (CLI)  ──►  scan_docs.py (ProcessPoolExecutor, extractors, embed_docs.py)
ensure_ollama.py            doc_search.py (HTTP :8643)
                                   │                   │
                                   └────────┬──────────┘
                                            ▼
                         du-docs.db (SQLite FTS5)  +  Ollama
                         (nomic-embed-text, dolphin3)

Keyword scoring uses FTS5 BM25 with title and author weighted above body and tags. Semantic scoring compares query embeddings with document embeddings. Hybrid keeps the stronger of the two scores per document. See the README for the full algorithm.

Security

DocuBrowse binds to 127.0.0.1 and is meant for single-user local use. It is hardened so a malicious web page you visit cannot reach it:

Host-header allow-list defeats DNS rebinding.
CSRF tokens on every state-changing action, plus a loopback Origin/Referer check.
No stored-data injection: document fields are HTML-escaped and card actions use delegated listeners, not inline handlers.
Validated PII purge: SSNs against SSA allocation rules, cards by length, issuer prefix and Luhn, routing numbers by ABA checksum.

There is no user login because only you, on your own machine, can reach the server.