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 |
Review & Candidates
| Command | Description | |||
|---|---|---|---|---|
| `review list\ | show\ | accept\ | reject` | Inspect and resolve staged approval bundles |
| `candidate list\ | promote\ | archive` | Inspect and resolve staged concept and entity candidates |
Graph Tools
| Command | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| `graph query\ | path\ | explain\ | god-nodes\ | blast\ | stats\ | validate\ | update` | Run deterministic local graph navigation, impact-analysis, 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\ | --svg\ | --graphml\ | --cypher\ | --json\ | --obsidian\ | --canvas` | Export the graph workspace in shareable, 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 | Explicitly install agent rules for Codex, Claude, Cursor, Goose, Pi, Gemini, OpenCode, Aider, Copilot, Trae, Claw, and Droid, with optional graph-first hooks for Codex, Claude, OpenCode, Gemini, and Copilot |
Global Options
--version- Show version number--help- Show help for any command