Skip to content

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.

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

Requires running inside a git repository.

Terminal window
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 status
basemind 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.
Terminal window
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.
Terminal window
basemind admin repo
basemind admin telemetry [--window today|1h|24h|all] [--tool]
basemind admin tokens --stdin
basemind 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.

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

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

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

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.

Terminal window
basemind comms daemon
basemind comms start
basemind comms stop [--all]
basemind comms status
basemind 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.
Terminal window
basemind scan [--staged | --rev <REV>] [--no-git-history --rebuild-git-history] [--documents-*]
basemind rescan [PATH...] [--no-git-history --rebuild-git-history]
basemind watch
basemind serve
basemind status
basemind doctor
basemind completions <bash|zsh|fish|elvish|powershell>
basemind man
basemind 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|clean
basemind hook install [--force]
basemind cache stats
basemind cache gc [--dry-run]
basemind cache clear [--component]
basemind daemon ensure
basemind 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.

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.