BLZ Agent Instructions
Purpose
- Local, fast search over llms.txt/llms-full.txt with exact line ranges.
Canonical handle
- Use "source" as the canonical identifier for a document. Prefer `--source` (or `-s`) and positional SOURCE where available.
Recommended defaults
- export BLZ_OUTPUT_FORMAT=json # agent-friendly default across search/list/anchors/docs
Core Commands
- Add source (non-interactive): blz add <alias> <llms.txt-url> -y
- Update all sources: blz update --all
- List sources (JSON): blz list --format json
- CLI docs (Markdown): blz docs --format markdown
- CLI docs (JSON): BLZ_OUTPUT_FORMAT=json blz docs
Search
- All sources: blz search "<query>" --format json
- By source: blz search "<query>" --source <source> --format json
(also supports -s)
- Pagination: --limit <N> --page <P> [--last]
- Exact phrase: blz search '"claude code"' --format json
- Require phrases/words: blz search '+"claude code" +"computer use"'
> ⚠️ Compatibility: `--output`/`-o` is deprecated starting in v0.3. Use `--format`/`-f`. The alias remains temporarily for compatibility but emits a warning and will be removed in a future release.
JSON output shape (search)
- Top-level: { query, page, limit, totalResults, totalPages, totalLinesSearched, searchTimeMs, sources, results, suggestions? }
- Each result: { alias, file, headingPath[], lines, lineNumbers[], snippet, score, sourceUrl, checksum }
Get Exact Lines
- Fetch text: blz get <alias> --lines <range> [--context N]
- Ranges: "A-B" | "A+N" | "A:B,C:D"
Agent Flow (recommended)
1) Ensure source exists (blz list --format json); if missing, blz add <alias> <url> -y
2) Search for topic (blz search "<query>" --source <alias> --format json)
3) Pick top result; extract alias + lines
4) Fetch content (blz get <alias> --lines <lines> --context 3)
Notes
- Prefer llms-full.txt when available (updates may auto-upgrade with --yes; configurable default).
- Exit codes: 0=ok, 1=user error, 2=system error.
- Use --quiet for clean JSON in scripts.
- blz list --status to include ETag, Last-Modified, checksum.
- Global default output via env: BLZ_OUTPUT_FORMAT=json|text|jsonl (alias `ndjson` still accepted)
- Canonical: use --source; reserve alias for future multiple-alias features
- Default operator is OR; use `+`/`AND` for required terms and nested quotes for phrases.
Shell completions
- Static: blz completions <bash|zsh|fish|powershell>
- Dynamic aliases & anchors (recommended):
- Fish: source scripts/blz-dynamic-completions.fish
- Zsh: source scripts/blz-dynamic-completions.zsh (after compinit)
- PS: . scripts/blz-dynamic-completions.ps1