CLI reference
Every subcommand of the mushroomdb binary. Each usage block is what mushroomdb --help
prints for it; the text under it is what the help leaves out.
Set up an assistant
install
mushroomdb install [--platform claude-code|cursor|codex|all] [--project|--user] [--db <path>]
[--command <path>] [--no-prewarm] [--delivery cli|mcp|both]
[--always-load|--no-always-load]
--delivery cli writes the skill and the hooks and registers no MCP
server: the skill teaches `mushroomdb <command>` instead (claude-code
only; cursor and codex are always registered as MCP servers)
--always-load marks the registered MCP server alwaysLoad, so the host
keeps its tools in context instead of deferring them; already the
default when --db names a store and a server is registered
(--delivery mcp|both) — --no-always-load opts out
Write the /mushroom skill + MCP server entry + the SessionStart and UserPromptSubmit hooks. Auto-detects platform and scope. --delivery cli writes no server entry: the skill teaches the binary instead. alwaysLoad on the server entry is on by default for an install that pins a store with --db. An install over a 0.6 one removes the hooks and git hook blocks 0.7 no longer ships
uninstall
mushroomdb uninstall [--platform claude-code|cursor|codex|all] [--project|--user] [--db <path>]
Remove exactly what install wrote (manifest-driven; leaves user files)
disable
mushroomdb disable [--platform claude-code|cursor|codex|all] [--project|--user]
turn an install off without removing it: hooks and MCP entry are
removed; the skill, the store and .gitignore stay
Turn an install off without removing it: strips the MCP entry, the hooks, and any git hook block a 0.6 install wrote. The skill, the store and .gitignore stay
enable
mushroomdb enable [--platform claude-code|cursor|codex|all] [--project|--user]
turn a disabled install back on
Turn a disabled install back on, re-resolving the command instead of replaying what disable removed
doctor
mushroomdb doctor [--project|--user] [--platform claude-code|cursor|codex|all]
verify an install: config entry, store, hooks, and a real stdio
handshake with the configured MCP command; exits 1 on any `fail`
Verify an install: config entry, npx reachability, store, lock, hooks, a 0.6 git hook left behind, a real stdio handshake, and duplicate-scope servers. Exit 1 on any fail
Serve a store
serve
mushroomdb serve <db-dir> [--addr 127.0.0.1:8080] [--token <secret>] [--role-token TOKEN:ROLE] [--ui <dist-dir>] [--no-ui] [--demo-if-empty] [--snapshot-every <secs>] [--restore-from <dir>] [--tls-cert <pem> --tls-key <pem>]
--restore-from seeds an empty <db-dir> from the newest backup under <dir>
(or from <dir> itself if it is one); a no-op when <db-dir> already holds a store
--tls-cert and --tls-key go together and need a build with the `tls` feature
Start the HTTP server + optional UI (default 127.0.0.1:8080; --token on non-loopback; --role-token TOKEN:ROLE). The UI is served only by a build that embeds it — npx, Docker and the release binaries do; cargo install does not
mcp
mushroomdb mcp <db-dir>|--auto [--all-tools]
--all-tools lists every served tool; the default lists the association tools on every store,
a store `ingest-git` built included (the rest stay callable, just unlisted)
Start a stdio MCP JSON-RPC server for agent tools. --all-tools lists all 25 served tools; the default lists 23
Ask a store
query
mushroomdb query <db-dir> [--query "MATCH ..."] [--role <name>] [--namespace <ns>] <cypher…>
--role answers as one of the store's roles and --namespace from one
namespace; together they intersect, so neither ever widens the other
and either one makes the query a read
Run a Cypher read or write (--query also accepted). Pass the statement in shell double quotes: single-quote Cypher strings; inside the double quotes backslash every dollar sign, double quote and backtick. --role <name> answers as one of the store’s roles and --namespace <ns> from one namespace; together they intersect, so neither widens the other, and either makes the query a read
asof
mushroomdb asof <db-dir> --commit N|--at <date> [--query "MATCH ..."] [--namespace <ns>]
--at takes an RFC 3339 date (2026-06-19, or 2026-06-19T12:00:00Z)
and resolves to the last commit at or before it; exactly one of
--commit and --at
Read-only view at a WAL commit or at a date (2026-06-19, or RFC 3339) — the last commit at or before it. Exactly one of the two. --namespace <ns> reads one namespace as it was then
why
mushroomdb why <db-dir> <a> <b>
every rule edge between two keys with the evidence that
derived it, or a note that there is none
Every rule edge between two keys with the evidence that derived it, or a note that there is none — the shell form of explain_association
stats
mushroomdb stats <db-dir>
Print node/edge/rule counts, plus a namespaces: line once a store has more than the implicit default one
suggest
mushroomdb suggest <db-dir>
Rank candidate linking rules (scored top-k 32, KeyMatch 512)
algo
mushroomdb algo pagerank <db-dir> [--top N] [--dir out|in|both]
mushroomdb algo wcc <db-dir> [--top N]
mushroomdb algo degree <db-dir> [--top N] [--dir out|in|both]
mushroomdb algo communities <db-dir> [--edge-type T]... [--weight-prop P] [--min-weight X] [--top N]
pagerank/wcc/degree — PageRank, weakly-connected components, or degree centrality over manual + derived edges. These three subcommands do not accept --weight-prop or --min-weight.
communities — Louvain community detection with per-community cohesion and overall modularity; accepts --edge-type (repeatable), --weight-prop and --min-weight.
Build and maintain a store
demo
mushroomdb demo <db-dir>
Write a deterministic demo graph (10 Orgs, 20 Projects, 30 People)
ingest-git
mushroomdb ingest-git <db-dir> <repo-dir> [--exclude <pattern>]... [--max-commits-per-file N]
[--recurse-submodules] [--prs] [--no-structure] [--no-docs] [--ensure-gitignore]
graph a git repo (authors, commits, files, symbols, imports, calls, mentions); re-run to sync
--recurse-submodules also walks each initialised submodule
--prs links merged pull requests via gh (skipped when gh is unavailable)
--no-structure skips the working-tree pass (no hashes, symbols, imports or calls)
--no-docs skips Markdown bodies, headings and mentions
--ensure-gitignore adds the database directory to the repo's .gitignore
with no --exclude the defaults apply: target/ node_modules/ dist/ .git/ *.lock *.min.js
Graph a git repository: Author, Commit, File, Symbol nodes plus CO_CHANGED, KNOWS, IMPORTS, CALLS and MENTIONS rules. Re-run to sync. See docs/site/ingest-git.md
schema
mushroomdb schema apply <db-dir> <schema.json>
mushroomdb schema apply <db-dir> --memory-defaults
applies the built-in memory schema to an existing store;
full-text on a populated store builds the index at each open until the next snapshot carries it
mushroomdb schema apply <db-dir> --memory-identity
adds the identity preset: sixteen SAME_AS rules over each entity's aliases;
says what it will backfill, then backfills
Idempotently apply a schema file (rules, views, fulltext indexes), the built-in memory schema, or the identity preset; prints a diff
build-index
mushroomdb build-index <db-dir> [--rule <name>]
drives a rule's vector index to completion a slice at a time, for an
operator who wants the build finished before traffic arrives; a rule
created over a large corpus derives no edges until its index is whole
Drive a rule’s vector index to completion a slice at a time, for an operator who wants the build finished before traffic arrives — a rule created over a large corpus derives no edges until its index is whole. After a restart, the first write or this command is what registers an unfinished build
snapshot
mushroomdb snapshot <db-dir> [--keep-wal|--truncate] [--retention N]
folds the WAL into snapshot.bin and archives it as wal.<N>.archive,
so node_history, edge_history, was_linked and asof keep reaching it;
--truncate discards it instead, --keep-wal leaves wal.bin whole
Write snapshot.bin and archive the WAL as wal.<N>.archive, so history reads still reach it. --truncate discards it; --keep-wal leaves wal.bin whole
verify
mushroomdb verify <db-dir> validate CRC32 integrity of every snapshot section
Audit snapshot integrity: CRC32 every section plus an rkyv structural pass over the mmap’d ones, exit 2 on any mismatch
migrate
mushroomdb migrate <db-dir>
Migrate an older store format in place
backup
mushroomdb backup <db-dir> <dest> process-local consistent copy of the database to <dest>
WARNING: unsafe against a concurrently running serve process;
use POST /backup on the HTTP server for live-serve backups
Copy store files to <dest> and CRC-verify the copy. WARNING: unsafe against a running serve — use POST /backup for live-served stores
export
mushroomdb export <db-dir> <dest> --format jsonl|parquet|graphml export all data
graphml writes one file: <dest>/graph.graphml if <dest> is an
existing directory, otherwise <dest> is the file path itself
(nodes + edges only; rules have no GraphML analogue)
Export nodes, edges, and rules. JSONL is byte-identical across runs; Parquet is not across library versions. GraphML exports nodes and edges only, as a single .graphml file, for import into generic graph viewers and analysis tools
Hook bodies
install wires these two into the assistant; they are not meant to be typed.
recall
mushroomdb recall <db-dir>|--auto hook body: reads a prompt payload on stdin, prints related graph facts
Hook body for the /mushroom skill’s UserPromptSubmit recall hook: reads a prompt payload on stdin and prints a recall digest for it — a question in ordinary words is enough — and nothing when the store has nothing to say. Wired automatically by install
brief
mushroomdb brief <db-dir>|--auto hook body: the store's schema in one block — labels,
edge types, history depth, roles and one worked call per
question kind; byte-stable, so a session host caches it once
The store’s schema in one block — labels, edge types, how deep its history runs, who may read it, and one worked call per question kind — capped at 4,000 bytes and byte-stable between runs. Hook body for SessionStart
Version and help
--version
mushroomdb --version
Print the CLI’s version and exit
--help
mushroomdb --help
Print the usage this page is generated from, and exit.
Defaults and resolution
The notes --help prints under its usage:
Default serve address is 127.0.0.1:8080. Non-loopback --addr requires --token or MUSHROOMDB_TOKEN.
install defaults: --platform auto-detect; scope auto (project inside a git checkout, else user);
the MCP entry runs `npx -y mushroomdb@<version>` unless a `mushroomdb` on PATH is this binary, or
--command names one (a relative --command or --db is anchored to the current directory).
--no-prewarm means no network and no resolution: neither the one-off package fetch nor locating the
package's binary, so every hook keeps the slower `npx` form.
install and uninstall take out the code-graph hooks and git hook blocks a 0.6 install wrote.
uninstall resolves the same scope and falls back to the other one when the inferred scope has no
manifest; undoing a Codex install needs --platform codex.
A project install inside a git checkout writes --auto rather than a store path, so each `git
worktree` gets its own store; outside a checkout, and with --db, the store is pinned to an absolute
path instead.
--auto resolves the database as $CLAUDE_PROJECT_DIR/mushroom-memory, else mushroom-memory at the
root of the working tree the current directory is in, else ~/.mushroomdb/memory.
Running several at once
Every CLI write command, the hooks, and a running mushroomdb serve coordinate
through one advisory LOCK file in the store directory, so they are safe to run against the same
store at the same time. A writer that cannot get the lock within two seconds exits 3 with
another mushroomdb process is writing; retry, having written nothing. Readers never take the
lock and never wait; recall opens read-only (read_only: true) so an unattended hook can never
delay a writer or fail because one is running. What the lock does not give you: cross-process
transactions, and subscription events for a peer’s writes — a commit absorbed by refresh() is
visible on the next read but notifies nobody. Full model:
docs/site/concurrency.md.
The HTTP endpoints serve answers are in the HTTP API.