basemind-cli

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.