DocsStart
Index and search
Start the server, index a repository, then search it, trace the impact of a change, walk its knowledge graph and keep facts about it.
Start the server
Everything - the CLI, your assistant, the web console and the VS Code extension - talks to one running BBM-Atlas:
bbm-atlas serve# → http://127.0.0.1:8000, and the web console at /console/It listens on loopback only, and keeps its data in one local file, so what you index survives a restart. --host and --port change where it listens; before listening beyond this machine, read Security.
Index a repository
bbm-atlas index ./my-repo --name my-repo# prints the repository, with its idbbm-atlas list # every indexed repository's idbbm-atlas show <repository_id> # files, symbols, languages, when it was indexed- The path is resolved on your machine and must be readable by the server. When the server limits what may be indexed (
BBM_ATLAS_INDEX_ROOTS), it must be under one of those directories. - Indexing again re-parses only the files that changed.
--fullre-parses everything. --backgroundqueues the index as a job and returns at once;bbm-atlas job <job_id>shows its progress, and--cancelstops it.- Twelve languages are parsed symbol by symbol: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Kotlin, C and C++. Swift, Scala, Dart, Elixir, Lua, Shell and SQL are indexed as whole-file modules.
Search
bbm-atlas search <repository_id> "how does checkout work?"A question is classified, planned, and answered from four sources ranked together: the code's structure, repository memory, the knowledge graph and semantic similarity. Each hit names its symbol, file and score, and which sources found it.
Trace the impact of a change
bbm-atlas impact <repository_id> shop.cart.checkout --max-depth 3 --tests- The symbol is named by its qualified name. An ambiguous name lists the candidates to choose from.
- The answer lists what depends on the symbol, hop by hop, and with
--teststhe tests that cover it. --relationship-type(repeatable:calls,imports,extends,implements) limits the walk to those relationships, and--backend graphwalks the persisted graph instead of the in-process map.
Walk the knowledge graph
| Command | Answers |
|---|---|
bbm-atlas graph query <repository_id> "payment retries" | The best entry point for a question, and the graph around it |
bbm-atlas graph path <repository_id> <from> <to> | The shortest path between two symbols |
bbm-atlas graph neighbors <node_id> | A node's relationships, by direction, type and confidence |
bbm-atlas graph cycles <repository_id> | Circular import chains |
bbm-atlas graph god-nodes <repository_id> | The most connected abstractions |
bbm-atlas graph communities <repository_id> | Subsystems: clusters of densely connected code |
bbm-atlas graph stats <repository_id> | Counts, confidence and when the graph was last indexed |
Every edge carries a confidence: extracted from the code, inferred, or ambiguous. --min-confidence keeps only the edges you trust.
Keep facts
Facts are what you, or your assistant, learn about a repository that the code doesn't say: a decision, a preference, a known quirk. They are recalled in later work.
bbm-atlas remember <repository_id> "Prices are integers in cents" --category decisionbbm-atlas recall <repository_id> --query pricesbbm-atlas forget <repository_id> <fact_id>Output and exit codes
Every command prints the server's JSON answer and exits 0 on success, 1 otherwise, so the CLI composes with jq and shell &&. Commands reach http://localhost:8000 unless --base-url (or BBM_ATLAS_CLI_BASE_URL) says otherwise, and send --api-key (or BBM_ATLAS_CLI_API_KEY) when the server requires one. The CLI reference lists every command.