Skip to content

CLI Reference

Complete command reference for agsuperbrain. Every command below is verified against the current codebase.

Run agsuperbrain --help for the live list, or agsuperbrain <command> --help for a single command's flags.

Command map

Category Commands
Setup init, doctor
Ingestion ingest, ingest-doc, ingest-audio
Indexing index-vectors, link
Querying ask, search-vectors, query, inspect-function
Analysis stats, report, cluster, visualize
Lifecycle watch, clean, export, import
MCP / IDE mcp-serve, install, <ide>-install, <ide>-uninstall

Setup

init

Initialize Super-Brain in the current project — one command does everything.

bash agsuperbrain init agsuperbrain init --path ./my-project agsuperbrain init --src ./apps/backend # explicit source directory agsuperbrain init --skip-ingest # config only; ingest later

Performs, in order:

  1. Writes .agsuperbrain/config.yaml, .agsuperbrainignore, and updates .gitignore and .claude/settings.json.
  2. Runs ingest on your project root. The extractor walks every subdirectory and automatically skips .venv, node_modules, __pycache__, .git, dist, build, .tox, and other standard noise — so one command works for flat Python, src-layout Python, Maven/Gradle/Spring Boot (src/main/java/…), Go (cmd/, internal/, pkg/), Rust crates, .NET solutions, Rails, Flutter (lib/), Swift (Sources/), Unity, Unreal, and monorepos. Override with --src <path> to target a specific workspace. Skip entirely with --skip-ingest.
  3. Runs index-vectors for semantic search (downloads an ~80 MB embedding model on first run).
  4. Starts the background file watcher so subsequent edits are incrementally re-indexed.

By the time init finishes, your graph is populated and your watcher is live.

doctor

Health check every component.

bash agsuperbrain doctor

Verifies: graph DB, vector DB, tree-sitter language pack, embedding model, optional FFmpeg. Reports any missing pieces with fix instructions.

Ingestion

ingest

Parse source code into the graph.

bash agsuperbrain ingest ./src agsuperbrain ingest ./src ./lib ./services

Walks every directory argument, picks files whose language tree-sitter supports, extracts functions/methods/classes and their call relationships, writes them to the graph. Pure AST — no LLM calls.

ingest-doc

Ingest documents (PDF, DOCX, PPTX, MD, TXT, HTML).

bash agsuperbrain ingest-doc ./design-docs agsuperbrain ingest-doc ./README.md ./ARCHITECTURE.md

Extracts sections, headings, and concepts; each becomes a graph node linked to its document.

ingest-audio

Transcribe and ingest audio or video.

bash agsuperbrain ingest-audio ./meetings/standup.mp3 agsuperbrain ingest-audio https://youtube.com/watch?v=xxxx

Accepts local files (MP3, WAV, MP4, etc.) or YouTube URLs. Uses local faster-whisper — nothing is uploaded. Segments become graph nodes with timestamps.

Requires FFmpeg on your PATH.

Indexing

index-vectors

Embed every function, document section, and transcript segment into the vector store for semantic search.

bash agsuperbrain index-vectors

Uses a local sentence-transformer model (~80 MB, downloaded on first run). Incremental on subsequent runs — only new/changed nodes are re-embedded.

Build cross-modal links between code, documents, and audio via keyword overlap.

bash agsuperbrain link

Run this after any combination of ingest, ingest-doc, ingest-audio to connect related content across modalities.

Querying

ask

Natural-language question with deterministic evidence.

bash agsuperbrain ask "how does DataProcessor initialize?" agsuperbrain ask "what validates JWT tokens?" --llm

Flags:

  • --llm — use the local LLM to phrase the answer. Without it, you get evidence directly.
  • --db <path> — override the graph DB path.

Returns the answer, the nodes used as evidence (score, hops, source file, line number), and the confidence score.

search-vectors

Pure semantic search over the vector index.

bash agsuperbrain search-vectors "payment processing" agsuperbrain search-vectors "error handling" --limit 10

Ranks all embedded nodes by cosine similarity.

query

Raw Cypher query against the graph.

bash agsuperbrain query "MATCH (f:Function) RETURN f.qualified_name LIMIT 10" agsuperbrain query "MATCH (f:Function)-[:CALLS]->(g:Function) WHERE f.name='main' RETURN g.qualified_name"

For advanced users who want to ask questions the high-level commands don't cover.

inspect-function

Show a function's full body, docstring, callers, and callees.

bash agsuperbrain inspect-function DataProcessor.process agsuperbrain inspect-function main

Accepts either a qualified name (ClassName.method) or a bare name (returns the first match).

Analysis

stats

Quick statistics about the graph.

bash agsuperbrain stats

Counts per node type (Module, Function, Class, Document, Section, Concept, Audio, Transcript, etc.) and per edge type.

report

Generate GRAPH_REPORT.md with god-nodes, cross-module dependencies, orphan modules, and suggested follow-up questions.

bash agsuperbrain report

Writes to the project root. Useful for onboarding a new teammate or auditing architecture drift.

cluster

Run Leiden community detection on the call graph.

bash agsuperbrain cluster

Groups functions into subsystems without any manual tagging. Results stored in the graph and visible via visualize.

visualize

Generate an interactive Cytoscape.js visualization.

bash agsuperbrain visualize output/graph.html agsuperbrain visualize output/graph.html --root DataProcessor.process --depth 2

Open the output HTML in any browser. Click nodes to navigate, drag to rearrange.

Lifecycle

watch

Foreground file watcher for manual control (the one started by init runs in the background).

bash agsuperbrain watch ./src # continuous agsuperbrain watch ./src --once # single pass then exit

Changes are detected by content hash, re-indexed incrementally, and deleted files are swept from the graph.

clean

Remove all Super-Brain data from the project.

bash agsuperbrain clean agsuperbrain clean --yes # skip confirmation

Deletes .agsuperbrain/ and its contents. Your code is untouched.

export

Dump the graph to a JSON file for backup or transfer.

bash agsuperbrain export ./backup.json

import

Load a graph from a JSON dump.

bash agsuperbrain import ./backup.json

Use together with export to move a graph between machines or snapshot a known-good state.

MCP / IDE integration

mcp-serve

Start the MCP server over stdio JSON-RPC.

bash agsuperbrain mcp-serve

Exposes ten tools to any MCP-compatible client: search_code, find_callers, find_callees, get_function_body, path_between, closure, get_subgraph, stats, list_modules, list_functions.

Most users don't run this manually — the <ide>-install commands wire it up for you.

install

Install Super-Brain integration for a specific platform or all of them.

bash agsuperbrain install --platform all agsuperbrain install --platform claude agsuperbrain install --platform cursor

Accepts: all, claude, cursor, aider, codex, opencode, vscode, openclaw, droid, trae, gemini, hermes, kiro, antigravity, copilot.

Per-platform install / uninstall

Each supported IDE has its own dedicated command:

bash agsuperbrain claude-install agsuperbrain claude-uninstall agsuperbrain cursor-install agsuperbrain cursor-uninstall agsuperbrain aider-install agsuperbrain aider-uninstall agsuperbrain codex-install agsuperbrain opencode-install agsuperbrain copilot-install agsuperbrain vscode-install agsuperbrain gemini-install agsuperbrain hermes-install agsuperbrain kiro-install agsuperbrain antigravity-install agsuperbrain openclaw-install agsuperbrain droid-install agsuperbrain trae-install

Uninstall commands exist for Claude, Cursor, and Aider today. For other platforms, integration is additive and non-destructive — remove the installed files manually (see IDE Integration for exact file paths).

Global flags

Most commands accept:

Flag Purpose Default
--db <path> Override graph DB path ./.agsuperbrain/graph
--path <path> Override project path (install commands) .

Exit codes

Code Meaning
0 Success
1 Error (details printed to stderr)
2 Bad CLI arguments

Next steps