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

Option playbook for humans and agents

Choose options by the answer depth the next step needs. The best call is usually the shallowest call that can produce enough evidence.

Closed-loop agent policy: start with skygrep --agent-fast for implementation-location questions, use skygrep --agent-context when the next reasoning step needs source text, add --include whenever the scope is known, and reserve --detail full for a narrowed file/folder or parsed documents where direct reads are unavailable. --agent-context automatically fuses path tokens, symbols, bounded ripgrep recall, source-type priors, compact chunk evidence, and confidence summaries. Use --answer only when the user asked for synthesis; use bounded rg -l or targeted rg only for exact lexical/regex needs or raw grep output.

For repeated GPT / Cloud Code / Superconductor-style tool calls, keep the process warm with skygrep serve --port 7878 and call skygrep --agent-daemon --agent-fast ... or skygrep --agent-daemon --agent-context .... --agent-daemon uses SKYGREP_DAEMON_URL when set, otherwise http://127.0.0.1:7878, and falls back in-process if no daemon is running.

Agent presets default to rule-based routing, no cascade, and confidence-aware first-pass evidence for bounded latency. Low-confidence JSON includes agent_summary, why_ranked, and a scoped follow-up probe. Add --llm-router or --cascade only when ambiguity is worth paying a local model call or deeper semantic refinement.

In 0.5.15, this policy is now first-class CLI UX rather than only a documented playbook: --agent-fast expands to JSON path anchors, --agent-context expands to compact JSON snippets, and --agent-daemon makes daemon-first repeated calls explicit. The underlying router is unchanged: path-only probes return compact JSON anchors, snippet probes return bounded evidence for the next LLM step, and daemon-first repeated calls avoid paying process startup and model warmup on every tool invocation.

In 0.5.16, those agent presets are bounded in the runtime as well as in the documentation. Machine-readable agent calls default away from the local LLM router and cascade unless explicitly requested, use shorter model budgets, skip heavyweight foreground refresh lanes, keep background indexing alive, return top-8 compact evidence by default, and filter low-confidence JSON candidates before an LLM consumes them.

In 0.5.17, --agent-context closes the old manual-fallback gap by treating bounded ripgrep, path tokens, symbols, chunk text, source-type priors, and symbol anchors as one hybrid recall substrate. JSON callers get optional agent_summary, why_ranked, evidence_bundle, source_type, and evidence_terms fields while the top-level schema remains a list of result objects for backward compatibility.

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.