| name | basemind-cli |
| description | Navigate codebases and manage caches via the basemind CLI — outlines, symbol search, reference/caller lookups, git history, blame, and diffs. For headless scripting, CI, or when driving the CLI more efficiently than interactive MCP calls. Shares the same index as the MCP server. |
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. |
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 serve process.
- Lists are capped (
--limit, default 100, max 1000).
- Matching on symbol names is substring-based;
code mode references with name: "bar" matches
Foo::bar() and bar() alike.
- Git tools require basemind to be running inside a git repository.
memory modes require basemind to be built with --features full
(or the individual documents / memory flags).- Memory is scoped by the normalized
origin remote URL — clones of the same repo share memory;
unrelated repos do not see each other's entries.
web modes scrape, crawl, and map require --features crawl.
