npm package: @swarmvaultai/cli
Description: Global CLI for SwarmVault.
Latest version: 0.7.26

# @swarmvaultai/cli

`@swarmvaultai/cli` is the global command-line entry point for SwarmVault.

It gives you the `swarmvault` command for building a local-first knowledge vault from files, audio transcripts, YouTube URLs, reStructuredText and DOCX documents, browser clips, saved query outputs, and guided exploration runs.

## Install

SwarmVault requires Node `>=24`.

```bash
npm install -g @swarmvaultai/cli
```

Installed commands:

- `swarmvault`
- `vault` as a compatibility alias

## First Run

```bash
mkdir my-vault
cd my-vault
swarmvault init --obsidian --profile personal-research
swarmvault init --obsidian --profile reader,timeline
swarmvault demo
swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://example.com/docs/getting-started
swarmvault source add ./exports/customer-call.srt --guide
swarmvault source session file-customer-call-srt-12345678
swarmvault source list
swarmvault source reload --all
sed -n '1,120p' swarmvault.schema.md
swarmvault ingest ./notes.md
swarmvault ingest ./customer-call.mp3
swarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ
swarmvault ingest ./repo
swarmvault add https://arxiv.org/abs/2401.12345
swarmvault compile --max-tokens 120000
swarmvault diff
swarmvault benchmark
swarmvault query "What keeps recurring?" --commit
swarmvault query "Turn this into slides" --format slides
swarmvault explore "What should I research next?" --steps 3
swarmvault lint --deep
swarmvault graph blast ./src/index.ts
swarmvault graph query "Which nodes bridge the biggest clusters?"
swarmvault graph explain "concept:drift"
swarmvault watch status
swarmvault watch --repo --once
swarmvault hook install
swarmvault graph serve
swarmvault graph export --report ./exports/report.html
swarmvault graph export --html ./exports/graph.html
swarmvault graph export --cypher ./exports/graph.cypher
swarmvault graph push neo4j --dry-run
```

## Commands

### `swarmvault init [--obsidian] [--profile <alias-or-presets>]`

Create a workspace with:

- `inbox/`
- `raw/`
- `wiki/`
- `wiki/insights/`
- `state/`
- `state/sessions/`
- `agent/`
- `swarmvault.config.json`
- `swarmvault.schema.md`
- optional `.obsidian/` workspace files when `--obsidian` is passed

The schema file is the vault-specific instruction layer. Edit it to define naming rules, categories, grounding expectations, and exclusions before a serious compile.

`--profile` accepts `default`, `personal-research`, or a comma-separated preset list such as `reader,timeline`. For fully custom vault behavior, edit the `profile` block in `swarmvault.config.json`; that deterministic profile layer works alongside the human-written `swarmvault.schema.md`. The `personal-research` preset also sets `profile.guidedIngestDefault: true` and `profile.deepLintDefault: true`, so guided ingest/source and lint flows are on by default until you override them with `--no-guide` or `--no-deep`.

### `swarmvault scan <directory> [--port <port>] [--no-serve]`

Quick-start a scratch vault from a local directory in one command.

- initializes the current directory as a SwarmVault workspace
- ingests the supplied directory as local sources
- compiles the vault immediately
- starts `graph serve` unless you pass `--no-serve`
- respects `--port` when you want a specific viewer port

Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.

### `swarmvault demo [--port <port>] [--no-serve]`

Create a temporary sample vault with bundled sources, compile it immediately, and launch the graph viewer unless you pass `--no-serve`.

- writes the demo vault under the system temp directory
- requires no API keys or extra setup
- is the fastest way to inspect the full init + ingest + compile + graph workflow on a clean machine
- respects `--port` when you want a specific viewer port

### `swarmvault diff`

Compare the current `state/graph.json` against the last committed graph in git.

- when a prior committed graph exists, prints added and removed nodes, pages, and edges
- when no git baseline exists, falls back to a summary of the current graph state
- supports `--json` for structured automation output

### `swarmvault source add|list|reload|review|guide|session|delete`

Manage recurring source roots through a registry-backed workflow.

- `source add <input>` supports local files, local directories, public GitHub repo root URLs such as `https://github.com/karpathy/micrograd`, and docs/wiki/help/reference/tutorial hubs
- by default `source add` registers the source, syncs it into the vault, runs one compile, and writes a source brief to `wiki/outputs/source-briefs/<source-id>.md`
- add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`, with `wiki/insights/` fallback for `insights_only`
- set `profile.guidedIngestDefault: true` when guided mode should be the default for `source add` and `source reload`, and use `--no-guide` for individual light-path runs
- `source list` shows every managed source with its kind, status, and current brief path
- `source reload [id]` re-syncs one source, or use `--all` to refresh everything in the registry and compile once
- `source review <id>` stages a lighter source-scoped review artifact
- `source guide <id>` remains a compatibility alias for the guided session flow
- `source session <id>` resumes the latest guided session for a managed source id, raw source id, source scope id, or session id
- `source delete <id>` unregisters the source and removes transient sync state under `state/sources/<id>/`, but leaves canonical `raw/`, `wiki/`, and saved output artifacts intact

Useful flags:

- `--all`
- `--guide`
- `--no-guide`
- `--answers-file <path>`
- `--no-compile`
- `--no-brief`
- `--max-pages <n>`
- `--max-depth <n>`

Managed sources write registry state to `state/sources.json`. Guided sessions write durable anchors to `wiki/outputs/source-sessions/` and session state to `state/source-sessions/`. In an interactive TTY, `--guide` can ask the session questions immediately; otherwise use `source session <id>` or `--answers-file <path>` to resume and stage the approval bundle later. Local directory entries remain compatible with `watch --repo`; remote GitHub and docs-crawl sources are manual `source reload` sources in this release.

Source-scoped artifacts are intentionally split by role:

| Artifact | Created by | Purpose |
|----------|-----------|---------|
| Source brief | `source add`, `ingest` (always) | Auto summary written to `wiki/outputs/source-briefs/` |
| Source review | `source review`, `source add --guide`, `ingest --review`, `ingest --guide` | Lighter staged assessment in `wiki/outputs/source-reviews/` |
| Source guide | `source guide`, `source add --guide`, `ingest --guide` | Guided walkthrough with approval-bundled updates in `wiki/outputs/source-guides/` |
| Source session | `source session`, `source add --guide`, `ingest --guide` | Resumable workflow state in `wiki/outputs/source-sessions/` and `state/source-sessions/` |

### `swarmvault ingest <path-or-url> [--commit]`

Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.

- local directories recurse by default
- directory ingest respects `.gitignore` unless you pass `--no-gitignore`
- repo-aware directory ingest records `repoRelativePath` and later compile writes `state/code-index.json`
- use `source add` instead when the same local directory, public GitHub repo root, or docs hub should stay registered and reloadable
- URL ingest still localizes remote image references by default
- YouTube URLs short-circuit to direct transcript capture instead of generic HTML fetch
- local file and archive ingest supports markdown, text, reStructuredText, HTML, PDF, Word, RTF, OpenDocument, EPUB, CSV/TSV, Excel, PowerPoint, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcripts, Slack exports, email, calendar, audio, structured config/data, developer manifests, images, and code
- add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`, with `wiki/insights/` fallback for `insights_only`
- set `profile.guidedIngestDefault: true` when guided mode should be the default for `ingest`, and use `--no-guide` to force a plain ingest for one run
- code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Bash/shell scripts, Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++, PHP, Ruby, PowerShell, Elixir, OCaml, Objective-C, ReScript, Solidity, HTML, CSS, and Vue single-file components

Useful flags:

- `--repo-root <path>`
- `--answers-file <path>`
- `--no-guide`
- `--include <glob...>`
- `--exclude <glob...>`
- `--max-files <n>`
- `--include-third-party`
- `--include-resources`
- `--include-generated`
- `--no-gitignore`
- `--no-include-assets`
- `--max-asset-size <bytes>`
- `--commit`

Repo ingest defaults to `first_party` material. The extra `--include-*` flags opt dependency trees, resource bundles, and generated output back in when you actually want them in the vault.

Large repo ingest now emits low-noise progress on materially large batches, and parser compatibility failures stay local to the affected source instead of aborting unrelated analysis.

Audio files use `tasks.audioProvider` when you configure a provider with `audio` capability. When no such provider is configured, SwarmVault still ingests the source and records an explicit extraction warning instead of failing. YouTube transcript ingest does not require a model provider.

When `--commit` is set, SwarmVault stages `wiki/` and `state/` changes and creates a git commit when the vault root is inside a git worktree. Outside git, it becomes a no-op instead of failing.

### `swarmvault add <url>`

Capture supported URLs through a normalized markdown layer before ingesting them into the vault.

- arXiv abstract URLs and bare arXiv ids become durable markdown captures
- DOI URLs and bare DOI strings normalize into article-style research captures
- generic article URLs use a readability-style capture path with normalized research frontmatter
- X/Twitter URLs use a graceful public capture path
- unsupported URLs fall back to generic URL ingest instead of failing
- optional metadata: `--author <name>` and `--contributor <name>`
- normalized captures record fields such as `source_type`, `source_url`, `canonical_url`, `title`, `authors`, `published_at`, `updated_at`, `doi`, and `tags` when available
- use `source add` instead when the URL is a public GitHub repo root or a docs hub that should stay synced over time

### `swarmvault inbox import [dir]`

Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles, HTML clip bundles, and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.

### `swarmvault compile [--approve] [--commit] [--max-tokens <n>]`

Compile the current manifests into:

- generated markdown in `wiki/`
- structured graph data in `state/graph.json`
- local search data in `state/search.sqlite`

The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.

For ingested code trees, compile also writes `state/code-index.json` so local imports and module aliases can resolve across the repo-aware code graph.

New concept and entity pages are staged into `wiki/candidates/` first. A later matching compile promotes them into `wiki/concepts/` or `wiki/entities/`.

With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.

Useful flags:

- `--approve`
- `--commit`
- `--max-tokens <n>`

`--max-tokens <n>` keeps the generated wiki inside a bounded token budget by dropping lower-priority pages from final `wiki/` output and reporting token-budget stats in the compile result. `--commit` immediately commits `wiki/` and `state/` changes when the vault lives in a git repo.

### `swarmvault benchmark [--question "<text>" ...]`

Measure graph-guided context reduction against a naive full-corpus read.

- writes the latest result to `state/benchmark.json`
- updates `wiki/graph/report.md` and `wiki/graph/report.json` with the current benchmark summary
- accepts repeatable `--question` inputs for vault-specific benchmarks
- compile and repo-aware refresh runs also keep the benchmark/report artifacts up to date by default

### `swarmvault review list|show|accept|reject`

Inspect and resolve staged approval bundles created by `swarmvault compile --approve`.

- `review list` shows pending, accepted, and rejected entry counts per bundle
- `review show <approvalId>` shows each staged entry plus its current and staged content, including a section-level change summary when available
- `review show <approvalId> --diff` adds a unified diff between current and staged content
- `review accept <approvalId> [targets...]` applies pending entries to the live wiki
- `review reject <approvalId> [targets...]` marks pending entries as rejected without mutating active wiki paths

Targets can be page ids such as `concept:approval-concept` or relative wiki paths such as `concepts/approval-concept.md`.

### `swarmvault candidate list|promote|archive`

Inspect and resolve staged concept and entity candidates.

- `candidate list` shows every current candidate plus its active destination path
- `candidate promote <target>` promotes a candidate immediately into `wiki/concepts/` or `wiki/entities/`
- `candidate archive <target>` removes a candidate from the staged set

Targets can be page ids or relative paths under `wiki/candidates/`.

### `swarmvault query "<question>" [--no-save] [--commit] [--format markdown|report|slides|chart|image]`

Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules.

By default, the answer is written into `wiki/outputs/` and immediately registered in:

- `wiki/index.md`
- `wiki/outputs/index.md`
- `state/graph.json`
- `state/search.sqlite`

Saved outputs also carry related page, node, and source metadata so SwarmVault can refresh related source, concept, and entity pages immediately.

Human-authored pages in `wiki/insights/` are also indexed into search and query context, but SwarmVault does not rewrite them after initialization.

By default, query uses the local SQLite search index. When an embedding-capable provider is available and `search.hybrid` is not disabled, semantic page matches are fused into the same candidate set before answer generation. `tasks.embeddingProvider` is the explicit way to choose that backend, but SwarmVault can also fall back to a `queryProvider` with embeddings support. Set `search.rerank: true` when you want the configured `queryProvider` to rerank the merged top hits. `--commit` immediately commits saved `wiki/` and `state/` changes when the vault root is inside a git repo.

### `swarmvault explore "<question>" [--steps <n>] [--format markdown|report|slides|chart|image]`

Run a save-first multi-step research loop.

Each step:

- queries the vault
- saves the answer into `wiki/outputs/`
- generates follow-up questions
- chooses the next follow-up deterministically

The command also writes a hub page linking the root question, saved step pages, and generated follow-up questions.

### `swarmvault lint [--deep] [--no-deep] [--web] [--conflicts]`

Run anti-drift and vault health checks such as stale pages, missing graph artifacts, contradiction findings, and other structural issues.

`--deep` adds an LLM-powered advisory pass that can report:

- `coverage_gap`
- `contradiction`
- `contradiction_candidate`
- `missing_citation`
- `candidate_page`
- `follow_up_question`

Set `profile.deepLintDefault: true` when deep lint should be the default for `swarmvault lint`, and use `--no-deep` when one run should stay structural only.

`--web` can only be used when deep lint is enabled, either explicitly with `--deep` or through `profile.deepLintDefault`. It enriches deep-lint findings with external evidence snippets and URLs from a configured web-search provider. Web search is currently scoped to deep lint; other commands (compile, query, explore) use only local vault state.

`--conflicts` filters the results down to contradiction-focused findings so you can audit conflicting claims without the rest of the lint output.

### `swarmvault watch [--lint] [--repo] [--once] [--code-only] [--debounce <ms>]`

Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. With `--code-only`, SwarmVault forces the narrower AST-only refresh path and skips non-code semantic re-analysis until you run a normal `compile`. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.

When `--repo` sees non-code changes under tracked repo roots, SwarmVault records those files under `state/watch/pending-semantic-refresh.json`, marks affected compiled pages stale, and exposes the pending set through `watch status` and the local graph workspace instead of silently re-ingesting them.

When `--repo` sees only code-file changes under tracked repo roots, SwarmVault takes the faster code-only path: it refreshes code pages and graph structure without re-running non-code semantic analysis for unchanged sources.

### `swarmvault watch status`

Show watched repo roots, the latest watch run, and any pending semantic refresh entries for tracked non-code repo changes.

### `swarmvault hook install|uninstall|status`

Manage SwarmVault's local git hook blocks for the nearest git repository.

- `hook install` writes marker-based `post-commit` and `post-checkout` hooks
- `hook uninstall` removes only the SwarmVault-managed hook block
- `hook status` reports whether those managed hook blocks are installed

The installed hooks run `swarmvault watch --repo --once --code-only` from the vault root so commit and checkout refreshes update code pages and graph structure quickly. Run a normal `swarmvault compile` when you also want non-code semantic re-analysis.

### `swarmvault mcp`

Run SwarmVault as a local MCP server over stdio. This exposes the vault to compatible clients and agents through tools and resources such as:

- `workspace_info`
- `search_pages`
- `read_page`
- `list_sources`
- `query_vault`
- `ingest_input`
- `compile_vault`
- `lint_vault`
- `blast_radius`

`compile_vault` also accepts `maxTokens` for bounded wiki output, and `blast_radius` traces reverse import impact for a file or module target.

The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, and includes `schemaPath` in `workspace_info`.

### `swarmvault graph serve`

Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, and local graph query/path/explain endpoints.

It also exposes `/api/bookmarklet` and `/api/clip`, so a running local viewer can ingest the current browser page through a bookmarklet without leaving the browser.

### `swarmvault graph query "<question>" [--dfs] [--budget <n>]`

Run a deterministic local graph traversal seeded from local search, graph labels, and matching group patterns.

### `swarmvault graph path <from> <to>`

Return the shortest high-confidence path between two graph targets.

### `swarmvault graph explain <target>`

Inspect graph metadata, community membership, neighbors, provenance, and group-pattern membership for a node or page.

### `swarmvault graph god-nodes [--limit <n>]`

List the most connected bridge-heavy nodes in the current graph.

### `swarmvault graph blast <target> [--depth <n>]`

Trace the reverse-import blast radius of changing a file or module.

- accepts a file path, module label, or module id
- follows reverse `imports` edges through the compiled graph
- reports affected modules by depth so you can estimate downstream impact before editing

### `swarmvault graph export --html|--html-standalone|--report|--svg|--graphml|--cypher|--json|--obsidian|--canvas <output>`

Export the current graph as one or more shareable formats:

- `--html` for the full self-contained read-only graph workspace
- `--html-standalone` for a lighter vis.js export with node search, legend, and sidebar inspection
- `--report` for a self-contained HTML graph report with stats, key nodes, communities, and warnings
- `--svg` for a static shareable diagram
- `--graphml` for graph-tool interoperability
- `--cypher` for Neo4j-style import scripts
- `--json` for a deterministic machine-readable graph package
- `--obsidian` for an Obsidian-friendly markdown vault that preserves wiki folders, appends graph connections, emits orphan-node stubs and community notes, copies assets, and writes a minimal `.obsidian/` config
- `--canvas` for an Obsidian canvas grouped by community

You can combine multiple flags in one run to write several exports at once.

Set `graph.communityResolution` in `swarmvault.config.json` when you want to pin the Louvain clustering resolution used by graph reports and Obsidian community output instead of relying on the adaptive default.

### `swarmvault graph push neo4j`

Push the compiled graph directly into Neo4j over Bolt/Aura instead of writing an intermediate file.

Useful flags:

- `--uri <bolt-uri>`
- `--username <user>`
- `--password-env <env-var>`
- `--database <name>`
- `--vault-id <id>`
- `--include-third-party`
- `--include-resources`
- `--include-generated`
- `--dry-run`

Defaults:

- reads `graphSinks.neo4j` from `swarmvault.config.json` when present
- includes only `first_party` graph material unless you opt into more source classes
- namespaces every remote record by `vaultId` so multiple vaults can safely share one Neo4j database
- upserts current graph records and does not prune stale remote data yet

### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid>`

Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.

Hook-capable installs:

```bash
swarmvault install --agent claude --hook
swarmvault install --agent gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent copilot --hook
```

Agent target mapping:

- `codex`, `goose`, `pi`, and `opencode` share `AGENTS.md`
- `claude` writes `CLAUDE.md`
- `gemini` writes `GEMINI.md`
- `aider` writes `CONVENTIONS.md` and merges `.aider.conf.yml`
- `copilot` writes `.github/copilot-instructions.md` plus `AGENTS.md`
- `cursor` writes `.cursor/rules/swarmvault.mdc`
- `trae` writes `.trae/rules/swarmvault.md`
- `claw` writes `.claw/skills/swarmvault/SKILL.md`
- `droid` writes `.factory/rules/swarmvault.md`

Hook semantics:

- `claude --hook` writes `.claude/settings.json` plus `.claude/hooks/swarmvault-graph-first.js` and adds model-visible advisory context through structured hook JSON
- `gemini --hook` writes `.gemini/settings.json` plus `.gemini/hooks/swarmvault-graph-first.js` and stays advisory/model-visible
- `opencode --hook` writes `.opencode/plugins/swarmvault-graph-first.js` and stays advisory/log-only
- `copilot --hook` writes `.github/hooks/swarmvault-graph-first.json` plus `.github/hooks/swarmvault-graph-first.js` and remains decision-based rather than advisory

`aider` is intentionally file/config-based in this release rather than hook-based.

### OpenClaw / ClawHub Skill

If you use OpenClaw through ClawHub, install the packaged skill:

```bash
clawhub install swarmvault
```

That published bundle includes `SKILL.md`, a ClawHub README, examples, references, troubleshooting notes, and release-validation prompts. The CLI binary still comes from npm:

```bash
npm install -g @swarmvaultai/cli
```

## Provider Configuration

SwarmVault defaults to a local `heuristic` provider so the CLI works without API keys, but real vaults will usually point at an actual model provider.

Example:

```json
{
  "providers": {
    "ollama-local": {
      "type": "ollama",
      "model": "qwen3:latest",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "capabilities": ["chat", "structured", "vision", "local"]
    }
  },
  "tasks": {
    "compileProvider": "ollama-local",
    "queryProvider": "ollama-local",
    "lintProvider": "ollama-local",
    "visionProvider": "ollama-local"
  }
}
```

Generic OpenAI-compatible APIs are supported through config when the provider follows the OpenAI request shape closely enough.

Deep lint web augmentation uses a separate `webSearch` config block. Example:

```json
{
  "webSearch": {
    "providers": {
      "evidence": {
        "type": "http-json",
        "endpoint": "https://search.example/api/search",
        "method": "GET",
        "apiKeyEnv": "SEARCH_API_KEY",
        "apiKeyHeader": "Authorization",
        "apiKeyPrefix": "Bearer ",
        "queryParam": "q",
        "limitParam": "limit",
        "resultsPath": "results",
        "titleField": "title",
        "urlField": "url",
        "snippetField": "snippet"
      }
    },
    "tasks": {
      "deepLintProvider": "evidence"
    }
  }
}
```

Search behavior is configurable separately from provider routing:

```json
{
  "search": {
    "hybrid": true,
    "rerank": false
  }
}
```

- `search.hybrid` defaults to enabled and merges full-text hits with semantic page matches when an embedding-capable provider is available
- `search.rerank` optionally asks the current `queryProvider` to rerank the merged top hits before query answers are generated

## Troubleshooting

- If you are running from a source checkout and `graph serve` says the viewer build is missing, run `pnpm build` in the repository first
- If a provider claims OpenAI compatibility but fails structured generation, declare only the capabilities it actually supports
- If `lint --deep --web` fails immediately, make sure a `webSearch` provider is configured and mapped to `tasks.deepLintProvider`
- If you still see a `node:sqlite` experimental warning on Node 24, upgrade to the latest CLI; current releases suppress that upstream warning during normal runs

## Links

- Website: https://www.swarmvault.ai
- Docs: https://www.swarmvault.ai/docs
- GitHub: https://github.com/swarmclawai/swarmvault