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 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 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.