blz-cli 0.3.3

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