Quickstart

SwarmVault can be learned in layers. Start with the one-command path, then use the step-by-step workflow when you want more control over sources, schema, review, and agent handoffs.

1. Install

npm install -g @swarmvaultai/cli
swarmvault --version

No API key is required for the first run. The built-in heuristic provider can initialize, ingest, compile, search, and query locally.

2. Run The Beginner Path

Create a scratch folder where the vault output should live, then point SwarmVault at a file, repo, docs folder, or public GitHub repo URL:

mkdir my-vault
cd my-vault
swarmvault quickstart ../your-repo

quickstart initializes the current directory as a vault, ingests the input, compiles wiki and graph artifacts, writes the share kit, and opens the local graph viewer. It is the beginner-friendly alias for swarmvault scan. Interactive file and directory runs show bounded stderr progress with the active file, so large PDFs and document folders do not look silent while extraction runs.

When you are unsure what to do next, run the read-only orientation command:

swarmvault next

It reports whether the folder is uninitialized, initialized, or compiled, then recommends the next safe commands.

For an artifact-only run:

swarmvault quickstart ../your-repo --no-serve

For a zero-input walkthrough:

swarmvault demo

3. Inspect What Was Written

After the first compile, open these first:

If you ran inside an existing source repo and want generated folders elsewhere, set SWARMVAULT_OUT=.swarmvault-out. Config and schema stay in the project root; raw/, wiki/, state/, agent/, and inbox/ resolve under the output directory.

init, quickstart, scan, and clone do not write project-local agent rule files by default. Run swarmvault install --agent <agent> for explicit setup, or set agents in swarmvault.config.json and pass --install-agent-rules when you intentionally want configured targets installed together.

4. Ask And Check

swarmvault next
swarmvault query "What are the key concepts?"
swarmvault doctor
swarmvault graph serve

query saves useful answers into wiki/outputs/ by default. doctor checks graph, retrieval, review queues, watch state, migrations, managed sources, and task state. graph serve opens the local workspace with graph navigation, search, page preview, approvals, candidates, and health actions.

5. Learn The Step-By-Step Loop

Use the manual loop when you want to shape the vault before compile:

swarmvault init --obsidian --profile personal-research
swarmvault ingest ./src --repo-root .
swarmvault ingest ./meeting.srt --guide
swarmvault add https://arxiv.org/abs/2401.12345
swarmvault compile
swarmvault next
swarmvault query "What is the auth flow?"
swarmvault graph serve

Use source add when the input should stay registered and refreshable:

swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://example.com/docs/getting-started
swarmvault source list
swarmvault source reload --all

Public GitHub repos can be pinned:

swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo

6. Discover More Power When Needed

For command-by-command details, use the CLI reference. For provider setup, start with Provider Config or Ollama.