Reference · CLI

Command cheatsheet — every command at a glance.

The bare form covers ~ 95 % of real-world use: skygrep "<your question>". No subcommand, no flags. The system auto-routes (LLM router → find / rg / semantic cascade), auto-indexes on first query, and auto-recovers when the embedder is upgraded (0.2.2+). The subcommand form below is for power use, admin, and CI.

First-time workflow (Python-safe, < 2 min)

# 0. confirm Python 3.9+ is available
python3 --version

# 1. install with the same Python that will own the CLI
python3 -m pip install --user skylakegrep

# 2. pull required models, one command per model
ollama pull bge-m3
ollama pull qwen2.5:3b

# 3. verify runtime, models, install path, and index state
skygrep doctor

# 4. register skygrep with your LLM CLI(s) — claude code / codex / etc.
skygrep setup

# 5. cd into any project (no manual index step needed)
cd ~/your-project

# 6. ask anything
skygrep "where does the cascade tau threshold get computed"

skygrep setup writes a managed instruction block that teaches agents to choose the right output depth. Re-running setup refreshes that block, and normal searches / skygrep doctor refresh older managed blocks after an upgrade. New integrations still require explicit setup.

Information-depth examples

In 0.5.13, semantic and mixed queries also use an adaptive candidate recall substrate before final cascade ranking. For agents, this means --json --content --detail standard can return compact path and evidence packs from include scope, indexed path tokens, symbols, chunk text, and bounded ripgrep recall. The required contract is still simple: use --include when the caller knows the scope, add --content when the next step needs source text, and use --detail full only after narrowing.

On macOS, python may not exist; use python3. If the shell cannot find skygrep after install, inspect python3 -m site --user-base, which -a skygrep, and python3 -m pip show skylakegrep. The usual PATH fix is:

export PATH="$(python3 -m site --user-base)/bin:$PATH"

The first query auto-indexes in the background and falls back to rg for the first ~ 1 s; subsequent warm queries land in 0.5–2 s.

Clean uninstall / reinstall

# Remove LLM-CLI snippets written by `skygrep setup`.
skygrep setup --uninstall || true

# Remove the Python package from the Python that installed it.
python3 -m pip uninstall -y skylakegrep

# Optional: delete local indexes/config. This does not delete your files.
rm -rf ~/.skylakegrep

# Optional: remove downloaded Ollama models.
ollama rm bge-m3
ollama rm qwen2.5:3b

# Reinstall.
python3 -m pip install --user --no-cache-dir skylakegrep
ollama pull bge-m3
ollama pull qwen2.5:3b
skygrep doctor

Flags for skygrep search (and the bare form)

The full --help is on every install. Quick reference:

Environment variables (0.5.x)

Reading the per-query telemetry footer (0.2.2+)

Every search prints a structured workflow footer so you can see which retrieval path answered your query and why:

╰─ done   0.42s · quality=BEST
   path     : cosine-cheap (high-confidence early-exit)
   router   : llm -> intent=mixed (0.83)
   evidence : σ-gap=0.0820 ≥ τ=0.0050 (adaptive)
   pool     : 1 filename + 0 lexical · cascade
   index    : 20s ago · 36 files · L2 symbols + graph prior

Field-by-field:

• path= — the retrieval strategy this query took. One of: cosine-cheap, cosine-escalated-rerank, rg-only, cascade-skipped. (The symbol-channel path will appear once the 0.3.x auto-router lands.)
• σ-gap=… → reason — Bayesian-evidence proxy that drove the cascade decision. High σ-gap = top-K candidates well-separated → cosine trusted, exit cheap. Low σ-gap = candidates tied → escalate to cross-encoder rerank.
• recovery=in-progress chunks=N/T coverage=N% ETA=Nm — only when the 0.2.2 recovery worker is active. Reads live from the metadata table.
• quality=BEST / quality=DEGRADED-recovery — at-a-glance "is this the full-quality semantic answer or partial during recovery". DEGRADED only means some files are still pending re-embed; your specific query may be unaffected.

Reference · configuration

Environment variables.

Configuration is read from environment variables on every invocation; there is no config file. Defaults assume a local Ollama server on the default port.