CLI Reference
Every MCP tool has a CLI command that builds the same arguments and prints the same answer;
tests/cli_parity/ enforces it. The CLI also keeps shorthands (code callers, git recent, …) and
administrative commands with no MCP tool (git churn, git by-path, code chunk, memory delete,
cache, admin telemetry), each declared CLI-only. Add --json to any tool subcommand to print the
tool’s JSON.
| MCP tool | CLI command |
|---|---|
code_outline |
code outline |
code_symbols |
code symbols |
code_read |
code read (alias expand) |
code_grep |
code grep |
code_search |
code search (alias semantic) |
code_refs |
code refs (alias references); shorthands callers, implementations, dependents, definition |
find_files |
code find; code files lists |
docs_search |
memory documents |
git_log |
git log; shorthands recent, touching, search, show, symbol-history |
git_blame |
git blame; shorthand blame-symbol |
git_diff |
git diff; shorthands status, diff-outline |
memory_save |
memory put |
memory_search |
memory search, memory get, memory list |
index_status |
status (admin repo prints the same payload) |
index_rescan |
rescan |
Flags with a closed set of values (--relation, --lane, --match, --window) are validated by
clap: a typo fails with exit code 2 and the valid choices listed, and the
completions offer them.
Every list command takes the paging and budget flags its tool takes:
| Flag | Effect |
|---|---|
--limit <N> |
Maximum entries. |
--cursor <TOKEN> |
Resume from the previous page’s next_cursor. |
--max-tokens <N> |
Token budget for the returned list (default 6000); the overflow is dropped and the response is flagged budgeted. |
--format, --l2, --path-contains, --no-context, --line-start / --line-end, --field,
--body-chars, --hash-mode, --no-embed and --no-files no longer exist; see
Upgrading.
| Group | Gate |
|---|---|
code, git, memory, admin |
always available |
agents, workspace |
--features comms |
Prebuilt downloads (Homebrew, npm, pip, GitHub releases) ship the build with comms.
code — code lookups
Section titled “code — code lookups”basemind code outline <path> [--limit --cursor --max-tokens]basemind code symbols <name> [--kind --fuzzy --limit --cursor --max-tokens]basemind code read <path> [--symbol <name> [--kind] | --line <n> [--end-line <m>]]basemind code grep <pattern> [--regex --path --language --context --limit --cursor --max-tokens]basemind code search <query> [--lane --limit --cursor --max-tokens]basemind code refs <name> [--relation --path --line --column --match --limit --cursor --max-tokens]basemind code callers <path> <name> [--limit --cursor --max-tokens]basemind code implementations <name> [--limit --cursor --max-tokens]basemind code dependents <module> [--limit --cursor]basemind code definition <path> <line> <name> [--column]basemind code find [query] [--path-prefix --language --limit --cursor --max-tokens]basemind code files [--path-prefix --language --limit --cursor --max-tokens]basemind code chunk <path> [--chunk-id --byte-start]| Command | Purpose |
|---|---|
outline <path> |
A file’s structure: symbols with kind, signature and 1-based lines, plus imports. Read this instead of the file. Code files only; documents are searched with memory documents. |
symbols <name> [--kind --fuzzy] |
Find a definition by name across every indexed file. Ranked: exact, prefix, substring, then (with --fuzzy) fuzzy subsequence. |
read <path> --symbol <name> [--kind] / read <path> --line <n> [--end-line <m>] |
One symbol’s source body, or a 1-based inclusive line span. Alias expand. |
grep <pattern> [--regex --path --language --context] |
Text search over the indexed code. The pattern is literal unless --regex. --path is a substring of the repo-relative path, not a glob. --context adds one line before and after each hit. |
search <query> [--lane hybrid|semantic|keyword] |
Search code by meaning; returns pointers, read a hit with code read. Alias semantic. Needs --features code-search. |
refs <name> [--relation callers|implementations|importers|definition --path --line --column --match exact|substring] |
Usages of a name. Without --path, every call site of the exact identifier; with --path, callers of the definition in that file. Alias references. |
callers <path> <name> |
Shorthand for refs <name> --path <path>. |
implementations <name> |
Shorthand for refs <name> --relation implementations. |
dependents <module> |
Shorthand for refs <module> --relation importers. |
definition <path> <line> <name> [--column] |
Shorthand for refs <name> --relation definition --path <path> --line <line>: the definition the reference binds to. |
find [query] [--path-prefix --language] |
Fuzzy file-name or path search, ranked by score; a listing when the query is omitted. Covers documents as well as code. |
files [--path-prefix --language] |
List indexed files, code and documents alike. |
chunk <path> [--chunk-id --byte-start] |
Fetch one code-search chunk body. CLI only. Needs --features code-search. |
git — git history
Section titled “git — git history”Requires running inside a git repository.
basemind git log [--path --query --author --symbol --rev --limit --cursor --max-tokens]basemind git blame <path> [--line --end-line --symbol --rev --limit --cursor]basemind git diff [path] [--from --to --structural]basemind git statusbasemind git recent [--limit --cursor --max-tokens]basemind git touching <path> [--limit --cursor --max-tokens]basemind git search <query> [--author --limit --cursor --max-tokens]basemind git show <rev>basemind git symbol-history <path> <name> [--limit --cursor]basemind git blame-symbol <path> <name> [--rev --limit --cursor]basemind git diff-outline <path> [--rev]basemind git churn [--window --top-k]basemind git by-path <pattern> [--window --limit --cursor --max-tokens]| Command | Purpose |
|---|---|
log [--path --query --author --symbol --rev] |
No flags: recent commits. --path: commits touching a file, or a directory when it ends with /. --query / --author: full-text search. --path with --symbol: when that symbol’s body changed. --rev: that one commit in full. |
blame <path> [--line --end-line --symbol --rev] |
Who last changed a file, a 1-based line span, or one symbol. |
diff [path] [--from --to --structural] |
No arguments: working-tree status. A path alone: that file’s working-tree diff against HEAD. --from / --to: diff between revisions. --structural: symbols added and removed instead of text hunks. |
status |
Shorthand for diff with no arguments. |
recent |
Shorthand for log with no filter. |
touching <path> |
Shorthand for log --path <path>. |
search <query> [--author] |
Shorthand for log --query <query>. |
show <rev> |
Shorthand for log --rev <rev>. |
symbol-history <path> <name> |
Shorthand for log --path <path> --symbol <name>. |
blame-symbol <path> <name> [--rev] |
Shorthand for blame <path> --symbol <name>. |
diff-outline <path> [--rev] |
Shorthand for diff <path> --structural --from <rev>. |
churn [--window --top-k] |
Top files by commit count over a recent window. CLI only. |
by-path <pattern> [--window] |
Commits whose changed paths match a regex. CLI only. |
memory — shared memory and documents
Section titled “memory — shared memory and documents”basemind memory put <key> <value> [--tag <t>]... [--individual]basemind memory search <query> [--limit --tag --individual]basemind memory get <key> [--individual]basemind memory list [--prefix --tag --limit --individual --cursor]basemind memory delete <key> [--individual]basemind memory documents <query> [--mime-type --keywords --entity --scope --limit --cursor --max-tokens]| Command | Purpose |
|---|---|
put <key> <value> [--tag --individual] |
Write a durable note (memory_save). --individual uses the per-agent tier instead of shared (group). |
search <query> [--limit --tag --individual] |
Search stored notes by meaning. |
get <key> [--individual] |
Read one note by key. |
list [--prefix --tag --limit --individual] |
List notes, optionally by key prefix or tag. |
delete <key> [--individual] |
Remove a note by key. CLI only. |
documents <query> [--mime-type --keywords --entity --scope] |
Semantic search over indexed documents (docs_search) instead of opening them. |
admin — administration
Section titled “admin — administration”basemind admin repobasemind admin telemetry [--window today|1h|24h|all] [--tool]basemind admin tokens --stdinbasemind admin eval --tasks <FILE> [--out --report --markdown --baseline --tolerance --cost-tolerance --min-recall --warmup --mode]status, rescan and cache stats|gc|clear live at the top level
(see Other commands).
| Command | Purpose |
|---|---|
repo |
The same payload as status: index health plus repository branch and HEAD sha. |
telemetry [--window --tool] |
Aggregate recorded tool calls into a usage and token-savings summary. CLI only. |
tokens --stdin |
Count tokens in stdin with the o200k tokenizer and print just the integer (needs the tokenizer feature, which documents includes). CLI-only; no --json envelope. |
eval --tasks <FILE> [...] |
Score retrieval quality, latency and token savings over a JSONL task file. CLI-only; see Evaluation. |
agents — multi-agent coordination
Section titled “agents — multi-agent coordination”Requires --features comms. A thread is addressed by at least two of --subject, --path, and
--member; thread-start rejects fewer than two. Every command accepts --as-agent <id> to act as
a named sub-identity instead of the CLI’s default agent (used for orchestrating several named
subagents).
basemind agents register [--name --description --version --skill --as-agent]basemind agents list [--thread --as-agent]basemind agents thread-start [--subject --path --member --as-agent]basemind agents thread-list [--subject-contains --include-archived --as-agent]basemind agents join <thread> [--as-agent]basemind agents leave <thread> [--as-agent]basemind agents members <thread> [--as-agent]basemind agents add-member <thread> <member> [--as-agent]basemind agents remove-member <thread> <member> [--as-agent]basemind agents archive <thread> [--as-agent]basemind agents post <thread> <subject> [--body --tag --reply-to --as-agent]basemind agents history <thread> [--cursor --limit --since-hours --as-agent]basemind agents message <message-id> [--as-agent]basemind agents inbox [--cursor --limit --mark-read --since-hours --as-agent]basemind agents ack [--message-id --thread --to-seq --as-agent]basemind agents wait [--thread --timeout-secs --since-hours --cursor --as-agent]basemind agents cleanup [--dry-run --apply --message-ttl-hours --thread-idle-hours --thread-retention-hours --agent-ttl-hours --claim-ttl-hours --as-agent]basemind agents status [--agent-ttl-hours --as-agent]| Command | Purpose |
|---|---|
register [--name --description --version --skill --as-agent] |
Publish or update this agent’s identity card with the broker. |
list [--thread --as-agent] |
Agents known to the broker, optionally restricted to one thread’s members. |
thread-start [--subject --path --member --as-agent] |
Open a thread addressed by subject, path-glob, and/or members. |
thread-list [--subject-contains --include-archived --as-agent] |
Threads discoverable to you: membership, cwd path-match, or subject filter — never all threads. |
join <thread> [--as-agent] |
Join a thread so its messages reach your inbox. |
leave <thread> [--as-agent] |
Leave a thread you joined. |
members <thread> [--as-agent] |
Who belongs to a thread. |
add-member <thread> <member> [--as-agent] |
Add an agent to a thread you created. |
remove-member <thread> <member> [--as-agent] |
Remove an agent from a thread you created. |
archive <thread> [--as-agent] |
Close a thread; creator or human admin only. |
post <thread> <subject> [--body --tag --reply-to --as-agent] |
Send a message to a thread. |
history <thread> [--cursor --limit --since-hours --as-agent] |
A thread’s messages as front-matter only; bodies come from message. |
message <message-id> [--as-agent] |
Read one message body by id — the only path to a body. |
inbox [--cursor --limit --mark-read --since-hours --as-agent] |
Unread messages across your joined threads, front-matter only. --mark-read advances read cursors. |
ack [--message-id --thread --to-seq --as-agent] |
Clear messages you have read from your inbox. |
wait [--thread --timeout-secs --since-hours --cursor --as-agent] |
Block until a peer posts, or the timeout elapses (default 30s, capped at 40s so the call ends before typical MCP host timeouts). |
cleanup [--dry-run --apply ...] |
Preview stale agent, claim, message and thread retention; --apply performs it. TTL flags override the windows in hours. |
status [--agent-ttl-hours --as-agent] |
Active and stale agent counts plus the last maintenance time. |
workspace — machine-wide repo/worktree registry
Section titled “workspace — machine-wide repo/worktree registry”Requires --features comms. Read-only listings of the daemon’s registry; they have no MCP tool.
basemind workspace workspaces [--as-agent]basemind workspace worktrees <repo-id> [--as-agent]basemind workspace branches <repo-id> [--as-agent]| Command | Purpose |
|---|---|
workspaces [--as-agent] |
Every repository the machine daemon has indexed. |
worktrees <repo-id> [--as-agent] |
Git worktrees of a registered repo, with their branches. |
branches <repo-id> [--as-agent] |
Branches known to a registered repo. |
comms — broker daemon lifecycle
Section titled “comms — broker daemon lifecycle”Requires --features comms. This is the ONLY surviving basemind comms surface — the messaging
verbs it used to carry (register, agents, thread-start, threads, join, post, read,
inbox, wait, …) now live under basemind agents (above); comms read <id> became
agents message <id>, comms agents became agents list, comms threads became
agents thread-list.
basemind comms daemonbasemind comms startbasemind comms stop [--all]basemind comms statusbasemind comms doctor [--probe --clear-fatal]basemind comms cleanup [--dry-run --older-than <days>]| Command | Purpose |
|---|---|
daemon |
Run the broker loop in the foreground: bind the singleton socket, serve front-ends, block until shutdown. |
start |
Ensure the daemon is running (spawn if needed); no-op when already alive. |
stop [--all] |
Ask the running daemon to drain and stop. --all stops every live daemon of this version’s protocol generation on this machine, not just the current one; a 0.33 daemon is stopped with the 0.33 binary. |
status |
Report the daemon’s pid / version / uptime / room + subscriber counts. |
doctor [--probe --clear-fatal] |
List every live daemon of this version’s protocol generation on this machine (pid / comms dir / version / uptime), flag a pile-up over the ceiling, and prune dead registry entries. Reports process liveness only unless --probe is given, which also asks each daemon whether it can serve. --clear-fatal acknowledges and deletes the recorded fatal store error for this comms dir. |
cleanup [--dry-run --older-than <days>] |
Remove rendezvous files no daemon uses: other protocol generations’ directories and the files releases up to 0.33 left in the comms directory, when this command can take their daemon.lock and nothing in them changed for 30 days. --older-than 0 drops the age test, so another release’s message store goes as soon as none of its daemons runs. An entry without a daemon.lock is skipped. Never touches this version’s generation and contacts no daemon. |
Other commands
Section titled “Other commands”basemind scan [--staged | --rev <REV>] [--no-git-history --rebuild-git-history] [--documents-*]basemind rescan [PATH...] [--no-git-history --rebuild-git-history]basemind watchbasemind servebasemind statusbasemind doctorbasemind completions <bash|zsh|fish|elvish|powershell>basemind manbasemind init [--yes --with --without --rules-target --settings-target --config-dir .config|.config/basemind --no-rules --no-usage-rules --no-setup-notes --print]basemind lang list|install|cleanbasemind hook install [--force]basemind cache statsbasemind cache gc [--dry-run]basemind cache clear [--component]basemind daemon ensurebasemind statusline| Command | Purpose |
|---|---|
scan [--staged | --rev <REV>] [--no-git-history --rebuild-git-history] |
Full index of the project. --staged indexes the git index instead of the working tree; --rev indexes a revision into a separate rev-<sha7> view. The --documents-* flags override the matching [documents] keys for this run (each also has a BASEMIND_DOCUMENTS_* env var). The --llm-* flags and BASEMIND_LLM_* variables are deprecated: still accepted, and ignored. Ctrl-C stops the scan cleanly. |
rescan [PATH...] [--no-git-history --rebuild-git-history] |
Update one or more paths incrementally, or the whole tree when no path is given. When the daemon is running the rescan is forwarded to it (the daemon is the sole index writer); otherwise it runs in-process under the workspace writer lock. Ctrl-C stops it cleanly. The summary (also when forwarded to the daemon) reports docs_degraded and doc_timeouts when non-zero. |
watch |
Long-running watcher; keeps the code map current as files change (no server). |
serve |
Ensure the daemon is up and relay this process’s stdio to it as the MCP server. The daemon keeps the index fresh. |
status |
Index health and repo identity for this workspace (index_status): file counts per language, scan state, cache directory, branch and HEAD. |
doctor |
Check root, config, index, grammars, pre-commit hook and daemon; exits 1 when a check fails. |
completions <shell> |
Print a shell completion script to stdout. |
man |
Print the man page (roff) to stdout. |
init [--yes --with --without --rules-target --settings-target --config-dir --no-rules --no-usage-rules --no-setup-notes --print] |
Re-runnable onboarding: write basemind.toml, select capabilities, inject usage rules into a gitignored local rules file by default, optionally auto-approve basemind’s tools in Claude Code settings. See Get started. |
lang list|install|clean |
Manage downloaded tree-sitter grammars. install also fetches every grammar marked preload = true under [languages.<name>]. |
hook install [--force] |
Add a git pre-commit hook that runs basemind scan --staged. Honours core.hooksPath, works in linked worktrees, never blocks a commit, and refuses to replace a hook basemind did not write unless --force (the old one is kept as pre-commit.bak). |
cache stats, cache gc [--dry-run], cache clear [--component --yes] |
Offline path directly against the machine-global cache. gc runs the real cross-workspace reference-counted sweep (blobs younger than six hours are kept; BASEMIND_BLOB_GC_GRACE_SECS overrides) and prints what it removed. The cache commands have no MCP tool. gc --dry-run only counts blobs and deletes nothing. --component is blobs, views, lance, git-cache (default), telemetry, all, or views:<name> for one view. Everything except git-cache is destructive: it prompts on a terminal and requires --yes otherwise (exit 2). clear exits 3 while a writer holds the workspace lock, and for blobs while the daemon runs; blobs is the machine-global extraction store shared by every workspace. |
daemon ensure |
Ensure the daemon’s streamable-HTTP MCP transport is up; idempotent. Needs --features comms. |
statusline |
Print a one-line summary of the daemon’s hot workspaces, for a shell statusline. Silent and exits 0 when no daemon is running. |
Output, exit codes and the daemon
Section titled “Output, exit codes and the daemon”Human output is a generic table or key/value view. Table cells and outline signatures wider than 200
characters are cut with an ellipsis (key/value fields never are), and the number of cut cells is
reported on stderr; --json always carries the full values. The timing footer (startup time plus the
tool’s own latency) and other diagnostics go to stderr, so stdout stays pipeable.
| Exit code | Meaning |
|---|---|
0 |
Success. |
1 |
Runtime error (I/O, scan failure, a tool reported an error, a failed doctor check). |
2 |
Usage error: a bad flag or value (clap), a path outside the repo, or a destructive command without --yes. |
3 |
Busy: another process holds the workspace writer lock. Retry later, or start the daemon so the call is forwarded. |
4 |
Unavailable: the operation needs the comms daemon and none is reachable. |
130 |
Interrupted (Ctrl-C). Work committed before the interrupt is kept; a second Ctrl-C aborts immediately. |
When the comms daemon is running it is the sole index writer, so the one-shot tool subcommands open
the store without the index and forward index-dependent work to the daemon: memory, code refs, the code grep trigram prefilter, and rescan. Without a daemon they read
the index directly and read-only.