CLI Reference
The SwarmVault CLI covers the full local workflow: quickstart, initialize, ingest, compile, query, chat sessions, context packs, task ledgers, static AI exports, retrieval, lint, automation, graph serving, and MCP access.
Installation
npm install -g @swarmvaultai/cliThe CLI is available as both swarmvault and vault.
Commands
Core Workflow
| Command | Description |
|---|---|
next | Read-only orientation command that recommends init, ingest, compile, query, review, or refresh work based on current vault state |
quickstart <file|directory|github-url> | Beginner path: initialize the current directory, ingest one input, compile it, and optionally launch the graph viewer |
init | Initialize a SwarmVault workspace |
demo | Create a temporary bundled sample vault and optionally launch the graph viewer |
scan <file|directory|github-url> | Compatibility quick-start alias behind quickstart and clone; still callable, hidden from default top-level help |
source add|list|reload|delete | Register recurring directories, public GitHub repos, and docs hubs, with branch/ref checkout options for GitHub sources |
ingest <input> | Ingest a local file or URL, with optional guided review and git commit |
add <url> | Capture arXiv, DOI, article, and X/Twitter URLs through a normalized markdown layer |
inbox import [dir] | Import captured files from the inbox |
compile | Compile wiki pages, graph data, and search, with optional approval staging, git commit, and token budgeting |
query <question> | Ask the compiled vault a question and save by default, with hybrid search when configured |
chat [question] | Ask the compiled vault in a persisted multi-turn session with resume, list, and delete controls |
context build|list|show|delete | Build and manage bounded agent-ready evidence packs from the compiled vault |
task start|update|finish|list|show|resume | Record durable task ledgers for agent work and handoffs |
memory start|update|finish|list|show|resume | Compatibility alias for the task ledger |
retrieval status|rebuild|doctor | Inspect, rebuild, or repair the local retrieval index |
doctor | Run a whole-vault health check across graph, retrieval, reviews, watch state, migrations, sources, and tasks |
explore <question> | Run a save-first multi-step exploration loop |
benchmark | Measure graph-guided context reduction and refresh graph-report trust artifacts |
lint | Run anti-drift and structural checks |
consolidate | Roll working-tier insight pages up into episodic, semantic, and procedural tiers |
Review & Candidates
| Command | Description |
|---|---|
review list|show|accept|reject | Inspect and resolve staged approval bundles |
candidate list|promote|archive|auto-promote|preview-scores | Inspect, score, and resolve staged concept and entity candidates |
Graph Tools
| Command | Description |
|---|---|
graph query|path|explain|god-nodes|blast|cycles|stats|validate|update | Run deterministic local graph navigation, impact-analysis, cycle detection, validation, stats, and code-only graph refresh commands |
diff | Compare the current compiled graph against the last committed graph |
graph serve | Start the graph viewer |
graph share | Print the generated share card, compact post text, visual SVG card, or portable share kit for the compiled graph |
graph export --html|--html-standalone|--report|--callflow|--svg|--graphml|--cypher|--json|--obsidian|--canvas | Export the graph workspace in shareable, directed-code-flow, interoperable, or Obsidian-native formats |
export ai | Write a static AI handoff pack with llms.txt, full text, JSON-LD graph data, manifest metadata, and per-page siblings |
Automation & Hooks
| Command | Description |
|---|---|
schedule list|run|serve | Run configured recurring jobs for compile, lint, query, and explore |
watch | Watch the inbox, optionally refresh tracked repos, force code-only refreshes, or run one refresh cycle |
watch status | Show pending semantic refresh entries for tracked repo changes |
check-update | Top-level compatibility alias for graph status |
update | Top-level compatibility alias for graph update |
cluster-only | Top-level compatibility alias for graph cluster |
tree | Top-level compatibility alias for graph tree |
merge-graphs | Top-level compatibility alias for graph merge |
clone | Top-level compatibility alias for scan |
hook install|uninstall|status | Manage local git hooks for repo-aware refreshes |
Compatibility aliases remain documented and callable, but the default swarmvault --help view now keeps the first screen focused on primary commands. Use swarmvault <command> --help for any alias or advanced command.
Agent Integration
| Command | Description |
|---|---|
mcp | Run the vault as a local MCP server |
install --agent / install status --agent | Explicitly install or inspect agent rules for Codex, Claude, Cursor, Goose, Pi, Gemini, OpenCode, Aider, Copilot, Trae, Claw, Droid, Kiro, Hermes, Antigravity, VS Code, Kilo, Devin, and skill-bundle targets, with optional graph-first hooks for supported agents and .mcp.json MCP-server registration for Claude via --mcp |
Global Options
--version- Show version number--help- Show help for any command