basemind-cli

basemind CLI — the scriptable interface

basemind has two equally-weighted surfaces: MCP (interactive tool calls) and CLI (scriptable commands). They share the same .basemind/ index 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 query 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 search-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 query symbol "X"	Substring match, optional --kind filter.
"What's the shape of file F?"	basemind query outline path/F	Add --l2 for calls + docs.
"What calls X?" (any name)	basemind query references "X"	Name match, no scope resolution.
"What calls this specific definition?"	basemind query callers path name [--kind]	Specific definition lookup.
"Trace the call graph?"	basemind query call-graph "name" [--direction --max-depth]	BFS over calls.
"What implements / extends X?"	basemind query implementations "X"	Rust, Python, TS/TSX, JS.
"What imports module M?"	basemind query dependents "M"	Reverse-lookup via imports.
"What files are indexed?"	basemind query list-files [--language --path-contains]	Filter by language/path.
"What changed recently?"	basemind git recent-changes [--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-file path / blame-symbol path name	Per-line / per-symbol.
"Where's the churn?"	basemind git hot-files [--limit N]	Churn-ranked files.
"What's dirty in the working tree?"	basemind git working-tree-status	Staged/unstaged summary.
"Diff a file between revs?"	basemind git diff-file path old new / diff-outline path	File / outline diffs.
"What's indexed?"	basemind query status	File count, languages, cache dir.
"What's HEAD / branch?"	basemind query repo-info	Branch, HEAD, origin.
"Regex over file contents?"	basemind query grep "pattern" [--language --path-contains]	Full-text search.
"Semantic search over docs?"	basemind memory search-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 cache stats	On-disk size + orphan accounting.
"Reclaim cache space?"	basemind cache gc	Reclaim orphaned blobs. Safe alongside serve.
"Clear caches?"	basemind cache clear --component blobs|views|all	Destructive; use CLI not MCP.
"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 [--no-serve]	Live re-index. --no-serve = no MPC server.
"Refresh the index after edits?"	basemind scan	Full or incremental scan.
"Per-tool activity summary?"	basemind telemetry	Histogram + estimated tokens saved.

Output format

By default, all commands return human-readable text. For machine consumption, add the global --json flag:

basemind query symbol "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 under .basemind/. 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 query symbol "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 query outline src/mcp/tools.rs --l2

Get all references to a function

basemind query references "process_file"

Find all callers of a specific definition

basemind query callers src/scanner.rs "process_file" --json

Show recent commits with changed files

basemind git recent-changes --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 cache stats
basemind cache gc          # reclaim orphaned blobs
basemind cache clear --component blobs  # clear blobs only

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; find_references("bar") matches Foo::bar() and bar() alike.
• Git tools require basemind to be running inside a git repository.
• Intelligence tools (search_documents, memory_*) 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 ingestion tools (web_scrape, web_crawl, web_map) require --features crawl.