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/toc/docs
Core Commands
- Add source (non-interactive): blz add <alias> <llms.txt-url> -y
- Refresh all sources: blz refresh --all # deprecated alias: 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
- Single span: blz get <alias>:<start-end> [-C N|--context all]
- Multi-range: blz get <alias> --lines "A-B,C-D" [-C N]
- Multi-source: blz get <alias1>:<start-end> <alias2>:<start-end> --format json
- Ranges syntax: "A-B" | "A+N" | comma-delimited list (e.g., "A-B,C,D-F")
JSON output shape (get)
- Top-level: { requests[], executionTimeMs?, totalSources? }
- Each entry in requests[]:
- Single range ⇒ `snippet`, `lineStart`, `lineEnd`, plus optional metadata (`checksum`, `contextApplied`, `truncated`).
- Multi-range ⇒ `snippet`/`lineStart`/`lineEnd` omitted; inspect `ranges[]`, where every span carries its own `lineStart`, `lineEnd`, and `snippet`.
- Each ranges[] item: { lineStart, lineEnd, snippet }
- Clipboard helpers: use `.snippet` when present; otherwise aggregate `ranges[].snippet` (e.g. `jq -r '.requests[0].ranges[] | "\(.lineStart)-\(.lineEnd)\n\(.snippet)'"`).
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 (or multiple hits across aliases)
4) Fetch content:
- single span: blz get <alias>:<lines> --context 3 --format json
- multi-range: blz get <alias> --lines "A-B,C-D" --context 2 --format json
- cross-source set: blz get bun:7105-7164 turbo:2656-2729 --context 2 --format json
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 & headings (recommended):
- Fish: source scripts/blz-dynamic-completions.fish
- Zsh: source scripts/blz-dynamic-completions.zsh (after compinit)
- PS: . scripts/blz-dynamic-completions.ps1