Command Reference

srz provides a unified CLI interface where root targets are automatically routed based on input structure, accompanied by specialized subcommands.

Key Features & Subcommands Quick Reference

1. Root Target Dispatch (srz <TARGET>)

srz <TARGET> [FLAGS]

How Target Auto-Detection Works

Instead of forcing you to memorize dedicated subcommands like srz web, srz file, or srz book, srz inspects the structure of your <TARGET> argument and dispatches it through specialized ingestion pipelines:

When <TARGET> begins with http:// or https://, the router analyzes the URL domain and path. Links pointing to youtube.com or youtu.be route directly to the YouTube timed-text caption client. If the URL path or query parameters indicate a syndication feed (such as .rss, .xml, .atom, or /feed), the target is parsed via the universal syndication engine. All other standard web links pass to the web scraper, where Mozilla Readability scores DOM container density to strip navigation bars, advertisements, and cookie notices.

Local targets receive similarly intelligent routing. If <TARGET> matches an existing file path or ends with a standard document extension (.pdf, .html, .md, or .txt), the document loader reads and validates the file under a 20 MB ceiling. Passing a single hyphen (-) tells srz to ingest data from standard input, enabling seamless pipeline integration with commands like git diff | srz -. Queries beginning with news route to the Google News RSS aggregator, while any remaining freeform text strings are treated as book titles, triggering concurrent metadata and synopsis resolution across Open Library and Wikipedia.

Global Flags

2. Interactive Terminal Explorer (srz browse)

srz browse [FLAGS]
# Aliases: srz tui, srz library

Launches an interactive, full-screen Ratatui terminal dashboard for exploring past reads and managing summaries.

Keybindings

3. Grounded Q&A & Multi-Turn Chat (srz ask)

srz ask [TARGET] [QUESTION] [FLAGS]
# Alias: srz chat

Performs question-answering grounded directly on document context, protected with prompt injection quarantine tags (<source_document>).

• Single-turn query against latest read:

  srz ask "What are the main findings?"
  

• Single-turn query against a specific document, web page, YouTube video, or remote PDF:

  srz ask assets/document.pdf "What are the primary conclusions?"
  srz ask "https://www.youtube.com/watch?v=5C_HPTJg5ek" "What are the key points in this talk?"
  

• Interactive multi-turn chat REPL:

  srz ask -i
  srz ask assets/document.pdf -i
  

  Inside the REPL, ask questions naturally. Type exit, quit, or press Ctrl+C / Ctrl+D to end the session.

Session Management Flags

• --chats: List saved persistent chat sessions stored in DuckDB.
• --resume <ID>: Resume a previous conversation session by ID.
• --show-chat <ID>: Print complete transcript of a past chat session.
• --delete-chat <ID>: Delete a saved chat session.

4. Live News Digests & Feeds (srz news)

srz news <TOPIC_OR_FEED_URL> [FLAGS]

Aggregates and synthesizes top news stories from Google News RSS topics or directly from syndication feeds.

• Search by Topic:

  srz news "artificial intelligence" -t week
  

• Summarize Direct RSS/Atom Feed:

  srz news "https://blog.rust-lang.org/feed.xml"
  # Or pass directly as root target:
  srz "https://blog.rust-lang.org/feed.xml"
  

• -t, --timeframe <TIMEFRAME>: Recency filter: week (default, past 7 days), day (past 24h), month (past 30 days), all.
• -l, --limit <N>: Maximum number of articles to aggregate (default: 5).

5. Offline BM25 Search (srz find)

srz find <QUERY>

Executes a local Robertson-Sparck Jones BM25 search ranking across your entire DuckDB reading history without internet access.

• 2.5× Title Weight Boost: Terms matching document titles receive 2.5× the weight of terms matching summary bodies.
• Document Length Normalization: Sized with tuned parameters ($k_1 = 1.2, b = 0.75$) to balance term repetition and document length.
• Extracts relevance-focused preview snippets centered around query terms.

6. Reading Analytics & History

# View recent reads, token metrics, and model speeds
srz history [--limit <N>]

# View reading habit telemetry, streaks, time saved, and P50/P95 throughput
srz stats

# Generate and open the interactive standalone HTML library dashboard
srz index [--open]

7. Analytical SQL Interface (srz query)

srz query "<SQL>" [FLAGS]

Executes an arbitrary read-only analytical SQL query against the local DuckDB database (srz.duckdb). Results are formatted into an aligned terminal table by default, or exported as CSV or JSON.

# Query model usage and token counts
srz query "SELECT model, count(*) AS runs, avg(tokens_per_second) FROM history GROUP BY model"

# Output as CSV
srz query "SELECT title, word_count, style FROM history" --csv

# Output as JSON
srz query "SELECT id, title, target_type FROM library LIMIT 5" --json

8. Library Vault & Data Export (srz export)

srz export --format <FORMAT> --output <PATH>

Exports your offline summarized library into standard portable formats:

• Markdown Vault (--format markdown): Exports every summary into an individual Markdown file equipped with Obsidian and Logseq-compatible YAML frontmatter (title, target_type, model, style, word_count, created_at, author, url).

  srz export --format markdown ~/Obsidian/Vault/Summaries/
  

• Structured JSON (--format json): Exports the entire library and metadata into a single formatted JSON file.

  srz export --format json ~/backup_library.json
  

• CSV (--format csv): Exports all library rows and timing metrics as a spreadsheet-friendly CSV.

  srz export --format csv ~/summaries.csv
  

• Parquet (--format parquet): Exports to compressed Apache Parquet for data science workflows with Polars, Pandas, or DuckDB CLI.

  srz export --format parquet ~/library.parquet
  

9. Storage & Cache Maintenance (srz cache)

srz cache <SUBCOMMAND>

• srz cache dir: Display the absolute path to the local cache directory (~/.cache/srz).
• srz cache size: Show disk usage broken down by pages, search metadata, summaries, and views.
• srz cache prune: Evict expired items based on age or disk size budget:

  srz cache prune --older-than 14d
  srz cache prune --max-size 500MB
  

• srz cache clean: Clear all cached web pages and view files.
  • --reset-db: Also wipes the permanent srz.duckdb analytics database.

10. Configuration Management (srz config)

srz config <SUBCOMMAND>

• srz config path: Display path to config.toml and report whether it exists.
• srz config show: Print currently active configuration settings.
• srz config init: Generate a starter ~/.config/srz/config.toml file tailored to your host RAM, CPU, and recommended context window.

11. Diagnostics & Recommendations (srz recommend, srz doctor, srz models)

# Instant hardware & model recommendation card
srz recommend
srz recommend --json

# Comprehensive diagnostic audit (hardware, LLM latency, n_ctx, DuckDB, cache, pager)
srz doctor

# List available models reported by the connected backend
srz models

Hardware Profiling & Diagnostic Advisories

Running srz recommend or srz doctor profiles your physical machine without invasive C FFI bindings. By inspecting host system characteristics via pure-Rust in-process hardware profiling (sysinfo), srz classifies your system into hardware tiers and suggests optimal model configurations:

The advisor recommends high-fidelity Google Gemma 4 models tailored to your physical RAM, matching the exact selection cards shown in Llama GUI (such as gemma-4 with size E4B or 26B-A4B at Q8_0 quantization) while configuring the full model ID (ggml-org/gemma-4-E4B-it-GGUF:Q8_0) for seamless backend API communication. It calculates your single-pass token synthesis ceiling—the approximate 70% threshold of your context window—beyond which map-reduce chunking activates.

When running srz doctor, the engine performs an active end-to-end audit: it pings the local LLM endpoint, probes operational context lengths (n_ctx) and concurrency slots (total_slots), and verifies the integrity of DuckDB databases and cache directories. If the connected runner is constrained by sub-optimal context sizing (under 8k tokens) or slot bottlenecks, srz doctor provides concrete terminal guidance to unlock maximum throughput.

For the complete tier-by-tier hardware breakdown, refer to the canonical Hardware Tier Reference Matrix.

12. Self Updates & Shell Completions

# Check for updates or upgrade in place
srz upgrade --check
srz upgrade

# Generate autocomplete scripts (bash, zsh, fish, powershell)
# Zsh (add to ~/.zshrc):
eval "$(srz completions zsh)"

# Bash (add to ~/.bashrc):
eval "$(srz completions bash)"

# Fish (add to ~/.config/fish/config.fish):
srz completions fish | source

# PowerShell (add to $PROFILE):
srz completions powershell | Out-String | Invoke-Expression