goldziher basemind CLI — the scriptable interface
basemind has two equally-weighted surfaces: MCP (interactive tool calls) and CLI (scriptable commands).
They share the same machine-global cache (Linux ~/.local/share/basemind/, macOS
~/Library/Application Support/basemind/; override BASEMIND_DATA_HOME) and are safe to run
alongside each other. Reach for the CLI
when you're scripting, batching queries, running in headless environments, or CI.
Capabilities
- Code map across 300+ languages — tree-sitter outlines, symbol search, references, callers, call graphs, implementations, dependents.
- Full-text + symbol search — indexed regex over content and substring symbol lookup.
- Git intelligence — history, blame, and structural diffs at symbol resolution, plus churn.
- Document RAG over 90+ file formats — PDFs, Office, HTML, email, images (OCR) → semantic search.
- Shared memory — per-repo, scope-keyed key-value + semantic memory across sessions.
- Web crawl — scrape / follow-link crawl into the searchable document store.
- Cache management — stats, garbage collection, selective and full clears.
When to reach for it
- Running in headless environments or CI pipelines.
- Batching multiple queries without interactive delays.
- Integrating basemind into shell scripts or non-MCP tooling.
- Controlling tool routing explicitly (no agent routing decisions).
- Clearing caches destructively (only the CLI allows
--component all).
basemind first, shell/grep/git fallback. Prefer basemind code / graph over reading files, over
grep/rg, and over naked git: use it for code parsing (outlines, references, callers), git
history / blame / diffs (basemind git), document extraction / RAG / keyword + entity (NER) /
summary (basemind memory documents), and web scraping / crawling / sitemaps
(basemind web scrape / crawl / map). Drop to raw shell, grep, or git only when no basemind
command covers the question.
Command routing (copy this into your mental model)
| Question | Command | Notes |
|---|---|---|
| "Where is X defined?" | basemind code symbols "X" |
Substring match, optional --kind filter. |
| "What's the shape of file F?" | basemind code outline path/F |
Add --l2 for calls + docs. |
| "What calls X?" (any name) | basemind code references "X" |
Name match, no scope resolution. |
| "What calls this specific definition?" | basemind code callers path name [--kind] |
Specific definition lookup. |
| "Trace the call graph?" | basemind graph calls "name" [--direction --max-depth] |
BFS over calls. |
| "What implements / extends X?" | basemind code implementations "X" |
Rust, Python, TS/TSX, JS. |
| "What imports module M?" | basemind code dependents "M" |
Reverse-lookup via imports. |
| "What files are indexed?" | basemind code files [--language --path-contains] |
Filter by language/path. |
| "What changed recently?" | basemind git recent [--limit N] |
Recent commits with paths. |
| "When did symbol X last change?" | basemind git symbol-history path name |
Cross-commit structural hash. |
| "Who wrote this line / symbol?" | basemind git blame path / blame-symbol path name |
Per-line / per-symbol. |
| "Where's the churn?" | basemind git churn [--window N --top-k K] |
Churn-ranked files. |
| "What's dirty in the working tree?" | basemind git status |
Staged/unstaged summary. |
| "Diff a file between revs?" | basemind git diff path old new / diff-outline path |
File / outline diffs. |
| "What's indexed?" | basemind admin status |
File count, languages, cache dir. |
| "What's HEAD / branch?" | basemind admin repo |
Branch, HEAD, origin. |
| "Regex over file contents?" | basemind code grep "pattern" [--language --path-contains] |
Full-text search. |
| "Semantic search over docs?" | basemind memory documents "query" |
Needs documents feature. |
| "Recall something stored earlier?" | basemind memory get "key" / list / search "q" |
KNN + exact match. |
| "Remember this for future sessions?" | basemind memory put "key" "value" |
Delete with memory delete "key". |
| "Cache size?" | basemind admin cache-stats |
On-disk size + orphan accounting. |
| "What cache space is reclaimable?" | basemind admin gc |
Report orphaned blobs without deleting them. |
| "Clear caches?" | basemind admin cache-clear --component blobs --confirm |
Destructive; views / all require the offline cache command. |
| "Pull this URL into RAG?" | basemind web scrape <url> |
Single page (requires --features crawl). |
| "Ingest a docs site?" | basemind web crawl <seed-url> |
Link-following crawl. |
| "What URLs exist on this site?" | basemind web map <url> |
Sitemap + link discovery. |
| "Keep index fresh?" | basemind watch |
Live re-index watcher; no MCP server (that's serve). |
| "Refresh the index after edits?" | basemind scan |
Full or incremental scan. |
| "Refresh changed paths?" | basemind admin rescan [path…] |
Re-index in the live server. |
| "Per-operation activity summary?" | basemind admin telemetry |
Histogram + estimated tokens saved. |
Output format
By default, all commands return human-readable text. For machine consumption, add the global --json flag:
basemind code symbols "parseQuery" --json
This returns the raw JsonSchema-derived response structure, same as MCP.
Setup (one-time per repo)
basemind scan
This walks the tree, parses with tree-sitter, and writes the content-addressed blob store +
Fjall inverted index into the machine-global cache (Linux ~/.local/share/basemind/, macOS
~/Library/Application Support/basemind/; override BASEMIND_DATA_HOME). A few seconds for small
repos, ~22 s for an ~80k-file TypeScript monorepo.
Re-run basemind scan after large changes, or run basemind watch to keep the index fresh.
Examples
Find where a symbol is defined
basemind code symbols "MapCache"
Output:
src/mcp/mod.rs:79:1 MapCache (struct)
src/mcp/mod.rs:88:1 MapCache (impl)
Show a file's outline before opening it
basemind code outline src/mcp/tools.rs --l2
Get all references to a function
basemind code references "process_file"
Find all callers of a specific definition
basemind code callers src/scanner.rs "process_file" --json
Show recent commits with changed files
basemind git recent --limit 5
Blame a symbol to see when its body last changed
basemind git blame-symbol src/scanner.rs "process_file"
Manage cache space
basemind admin cache-stats
basemind admin gc
basemind admin cache-clear --component blobs --confirm
Notes
- All paths are repository-relative with forward-slash separators.
- The CLI opens the index read-only; safe to run alongside a live
basemind serveprocess. - Lists are capped (
--limit, default 100, max 1000). - Matching on symbol names is substring-based;
codemodereferenceswithname: "bar"matchesFoo::bar()andbar()alike. - Git tools require basemind to be running inside a git repository.
memorymodes require basemind to be built with--features full(or the individualdocuments/memoryflags).- Memory is scoped by the normalized
originremote URL — clones of the same repo share memory; unrelated repos do not see each other's entries. webmodesscrape,crawl, andmaprequire--features crawl.