Command Line Interface
Nancy Brain provides a comprehensive command-line interface for managing your knowledge bases. All commands are automatically documented below.
Installation
CLI Reference
nancy-brain
Nancy Brain - Turn GitHub repos into AI-searchable knowledge bases.
Usage:
Options:
nancy-brain add-article
Add a PDF article to the configuration.
Usage:
Options:
--category TEXT Category to add article to
--description TEXT Description of the article
--help Show this message and exit.
nancy-brain add-new-user
Create a new Nancy Brain login user (uses NB_USERS_DB).
Usage:
Options:
nancy-brain add-repo
Add a repository to the configuration.
Usage:
Options:
nancy-brain build
Build the knowledge base from configured repositories.
The build command validates config/repositories.yml (and config/articles.yml
if provided) before starting. If validation fails, the command prints
detailed errors and exits with a non-zero status.
Usage:
Options:
--config TEXT Repository config file
--articles-config TEXT PDF articles config file
--embeddings-path TEXT Embeddings output path
--force-update Force update all repositories
--dry-run Show what would be done without executing the
build
--dirty Leave raw repos and PDFs in place after build
(don't cleanup)
--summaries / --no-summaries Generate document summaries during build
(local, custom OpenAI-compatible, or
Anthropic)
--batch-size INTEGER Index documents in batches (requires
embeddings.upsert support). 0 = disable
batching.
--max-docs INTEGER Stop after indexing this many document chunks
(for testing / limiting resource use). 0 = no
limit.
--category TEXT Limit build to a single repository category
(as defined in repositories.yml)
--repo TEXT Limit build to a single repository by name
(across all categories unless --category is
set).
--summaries-only Warm the summary cache per-repo then exit
without building the index. Pair with --repo
for one-node-per-repo cluster jobs.
--use-cached-ocr-only Only use cached OCR Markdown for PDFs. Missing
cache entries are deferred as needs_ocr.
--help Show this message and exit.
nancy-brain explore
Explore the knowledge base document tree structure.
Usage:
Options:
--embeddings-path TEXT Embeddings path
--config TEXT Config path
--weights TEXT Weights path
--prefix TEXT Path prefix to filter results
--max-depth INTEGER Maximum depth to traverse
--max-entries INTEGER Maximum number of entries to show
--help Show this message and exit.
nancy-brain import-ads
Import articles from an ADS private library into articles.yml.
Usage:
Options:
--library TEXT Name of the ADS private library to import [required]
--category TEXT Category key in articles.yml (default: journal_articles)
--output TEXT Path to articles.yml to update (default:
config/articles.yml)
--dry-run Show what would be added without writing
--help Show this message and exit.
nancy-brain import-bibtex
Import articles from a BibTeX file into articles.yml.
Usage:
Options:
-f, --file PATH Path to the .bib file to import [required]
--category TEXT Category key in articles.yml (default: journal_articles)
--output TEXT Path to articles.yml to update (default:
config/articles.yml)
--dry-run Show what would be added without writing
--help Show this message and exit.
nancy-brain import-env
Scan a dependency file and add GitHub-backed packages to repositories.yml.
Supported formats: conda environment.yml, requirements.txt / .in, pyproject.toml. Format is detected automatically from the filename.
Usage:
Options:
-f, --file PATH Dependency file to import: environment.yml,
requirements.txt, or pyproject.toml [required]
--category TEXT Override category key (default: derived from file)
--output TEXT Path to repositories.yml to update (default:
config/repositories.yml)
--dry-run Show what would be added without writing
--pin-versions Set ref to the exact pinned version (== specs only) for
each entry
--help Show this message and exit.
nancy-brain init
Initialize a new Nancy Brain project.
This command creates a minimal config/ directory with a repositories.yml
file to get you started. Edit the file and then run nancy-brain build.
Usage:
Options:
nancy-brain ocr
OCR utilities and cache warmers.
Usage:
Options:
nancy-brain ocr setup
Install or update the managed local OCR worker runtime.
Usage:
Options:
--shared-root PATH Override the managed shared worker install
root.
--python PATH Python executable used to create the worker
venv (defaults to the current interpreter).
--torch-index-url TEXT Optional PyTorch wheel index URL for the
isolated worker runtime.
--torch-version TEXT Optional torch version override for the
worker runtime.
--torchvision-version TEXT Optional torchvision version override for
the worker runtime.
--flash-attn / --no-flash-attn Attempt to install flash-attn into the
worker runtime.
--recreate Recreate the worker virtualenv from scratch
before installing packages.
--verify / --no-verify Verify the installed worker runtime after
setup.
--help Show this message and exit.
nancy-brain ocr status
Inspect the managed local OCR worker runtime.
Usage:
Options:
--shared-root PATH Override the managed shared worker install root.
--verify / --no-verify Verify the worker runtime imports instead of only
reporting files on disk.
--help Show this message and exit.
nancy-brain ocr warm
Warm OCR cache entries for PDFs.
Usage:
Options:
--cache-dir PATH OCR cache directory (defaults to the package
cache path).
--backend TEXT Preferred OCR backend (for example deepseek,
skip, or none).
--articles-config PATH Optional articles.yml to download before
warming OCR cache.
--base-path PATH Base path for downloaded PDFs and scan roots.
[default: knowledge_base/raw]
--recursive / --no-recursive Recurse into directories when scanning for
PDFs.
--help Show this message and exit.
nancy-brain ocr worker
Process one or more PDFs and emit JSON worker records.
The worker owns only the OCR markdown cache contract:
it may read or write knowledge_base/cache/pdf_ocr, but it does not
touch embeddings or summary caches.
Usage:
Options:
--cache-dir PATH OCR cache directory (defaults to the package cache path).
--backend TEXT Preferred OCR backend (for example deepseek, skip, or
none).
--help Show this message and exit.
nancy-brain search
Search the knowledge base.
Usage:
Options:
--limit INTEGER Number of results
--embeddings-path TEXT Embeddings path
--config TEXT Config path
--weights TEXT Weights path
--help Show this message and exit.
nancy-brain serve
Start the HTTP API server.
Usage:
Options:
nancy-brain ui
Launch the web admin interface.
Usage:
Options:
Configuration Files
Nancy Brain uses YAML configuration files:
repositories.yml
# Repository categories and sources
microlensing_tools:
- name: MulensModel
url: https://github.com/rpoleski/MulensModel.git
- name: pyLIMA
url: https://github.com/ebachelet/pyLIMA.git
general_tools:
- name: numpy
url: https://github.com/numpy/numpy.git
articles.yml
# PDF articles to index
research_papers:
- name: "Microlensing Survey Methods"
url: "https://arxiv.org/pdf/astro-ph/0123456.pdf"
description: "Comprehensive survey methods review"
reviews:
- name: "Neural Networks in Astronomy"
url: "https://example.com/nn-astro.pdf"
weights.yaml
# File type weights for search ranking
file_weights:
".py": 1.2 # Boost Python files
".md": 1.0 # Standard weight for docs
".rst": 1.0 # Sphinx documentation
".txt": 0.8 # Lower weight for plain text
Tips and Best Practices
Project Setup
- Always start with
nancy-brain init project-name - Configure
config/repositories.ymlbefore building - Use meaningful category names for organization
Building Knowledge Bases
- Use
--force-updatewhen repositories have been updated - Large repositories may take time to process
- Monitor disk space for embeddings storage
Searching Effectively
- Use specific technical terms for better results
- Combine multiple keywords:
"neural networks optimization" - Use
--limitto get more diverse results
Exploring Content
- Start broad with
nancy-brain explore - Use
--prefixto focus on specific areas - Adjust
--max-depthbased on repository structure
Development Workflow
nancy-brain init my-project- Edit
config/repositories.yml nancy-brain buildnancy-brain search "test query"nancy-brain uifor interactive exploration
Troubleshooting
Common Issues
Build fails with permission errors:
Search returns no results:
# Verify embeddings were built successfully
ls -la knowledge_base/embeddings/
nancy-brain explore --max-entries 5
UI won't start:
Memory issues during build:
- Process smaller repositories first
- Use --articles-config separately for PDFs
- Monitor system resources during build
For more troubleshooting tips, see Troubleshooting Guide.