blz-docs-search

BLZ Search Patterns

Fast local documentation search using blz. Search is local, free, and fast (~6ms) - try many queries.

Key Concepts

Full-text search, not semantic: blz uses BM25 ranking. Query with keywords that appear in docs:

• Good: "useEffect cleanup", "test configuration", "HTTP server"
• Bad: "How do I use useEffect?", "What's the best way to..."

Citations: Results include citations like bun:304-324 (source:start-end lines). Use these with blz find to retrieve content.

Quick Patterns

# Check available sources first
blz list --status --json

# Basic search
blz "test runner" --json

# Search specific source
blz "hooks" --source react --json

# Retrieve by citation
blz find bun:304-324 --json

# Retrieve with full section context
blz find bun:304-324 --context all --json

# Retrieve with surrounding lines
blz find bun:304-324 -C 5 --json

# Batch retrieve multiple citations
blz find bun:304-324 deno:500-520 --json

Search Strategy

1. Start specific: Use precise technical terms
2. Try variations: Synonyms, abbreviations, alternate terms
3. Check sources: Verify relevant docs are indexed
4. Multiple searches: Run 3-5 different queries - it's fast
5. Narrow by source: Use --source when you know the library

Retrieval Options

Flag	Use When
--json	Always (structured output)
--context all	Need full section
-C N	Need N lines before/after
-A N / -B N	Asymmetric context
--max-lines N	Limit large sections

Common Pitfalls

• Semantic queries: "Compare X vs Y" won't work. Search "X" and "Y" separately.
• Too broad: "authentication" returns too much. Try "JWT auth", "OAuth flow".
• Missing sources: Check blz list first. Add sources with blz add.
• One search only: Try multiple query variations.

MCP Alternative

For structured operations, MCP tools are also available:

// Search documentation
mcp__blz__blz_find({ query: "test runner" })

// Retrieve citations
mcp__blz__blz_find({ snippets: ["bun:304-324"] })

// List available sources
mcp__blz__blz_list_sources()

// Add new source
mcp__blz__blz_add_source({ alias: "react", url: "https://react.dev/llms.txt" })

// Learn blz usage
mcp__blz__blz_learn({})