CLI Reference

Every user-facing vant command. Signatures were verified against the command implementations in bin/ for this release. Every command also accepts -h or --help unless noted otherwise.

Core commands live in bin/vant.js. Everything else is bin/<command>.js, dispatched by the main entrypoint.

Start here

Command	Description
`vant setup`	Interactive first-run wizard
`vant start`	Full startup (migrate, health, sync, load, run)
`vant health`	System diagnostics
`vant help`	Show all commands and global flags
`vant version`	Show version (`-v`, `--version`)

vant setup
vant start              # Full startup; auto-migrates legacy brain layouts
vant start --no-sync    # Skip GitHub sync
vant start --local      # Skip GitHub entirely
vant start --no-migrate # Skip brain layout migration
vant health

Sync and brain

Command	Description
`vant sync`	Pull/push brain from/to GitHub
`vant hybrid`	Public/private brain split sync (routes bin/hybrid-sync.js)
`vant watch`	Poll GitHub for changes
`vant repos`	Mount and sync external repositories
`vant load`	Load brain files (.md, .json, .yaml, .ini, .txt)
`vant onboard`	Browse brain files interactively
`vant migrate`	Brain layout migration (multi-brain import)
`vant lock`	Brain write lock for multi-agent safety
`vant lineage`	Trace/audit trail for brain changes
`vant prune`	Prune old or stale brain files

vant sync               # Pull, then push
vant sync push          # Push only
vant sync pull          # Pull only

vant hybrid --public    # Push public brain only
vant hybrid --private   # Push private brain only

vant load               # Load brain from models/private
vant load --version 3   # Load a specific brain version
vant load --latest      # Force latest

vant onboard files      # List brain files

vant migrate --status   # Layout version and pending migrations
vant migrate --dry-run  # Preview what would move, no changes
vant migrate            # Apply pending migrations
vant migrate --brain-name mybrain  # Name the imported brain (default: vant)

vant lock acquire
vant lock release
vant lock status

vant migrate notes:

vant start runs migration automatically before health; --no-migrate skips it.
Detection is content-based, so it is safe to run at any time.
Every step is idempotent; a second run is a no-op.
A failed import is retryable: the marker is withheld and the next run retries.
Existing brain files are never clobbered; existing files are skipped.
vant health warns on legacy (pre-multi-brain) trees until migrated.
The import contract, naming rules, and troubleshooting are in the Migration Guide.

vant watch polls GitHub on an interval:

vant watch                # Poll GitHub for changes
vant watch --interval 30  # Poll every 30 seconds

Memory and search

The unified memory surface: key-value state, documents, geometric addressing. See Memory and Brain Search.

Command	Description
`vant memory`	Full memory CLI (state, learn, query, address, locate)
`vant search`	Search the brain corpus (basic, rag, hybrid, hyde)
`vant rerank`	Rerank and compress results for LLM context
`vant embed`	Embedding provider management
`vant citations`	Citation management
`vant geometry`	NSC9 quasicrystal storage (barcode addressing)

vant memory state <key> <value>    # Store state (TTL cache)
vant memory recall <key>           # Get state
vant memory learn <key> <content>  # Learn document (persists)
vant memory query <key>            # Query document
vant memory address <data>         # Store at geometric address
vant memory locate <barcode>       # Locate by barcode
vant memory list                   # Show stats
vant memory clear                  # Clear all

vant memory learn goals "Ship the T2 sweep."  # Store a document (persists)
vant memory recall goals                      # Recall state by key

vant search <query>                # Default: hybrid
vant search <query> --mode basic   # Text search
vant search <query> --mode rag     # Semantic LTC
vant search --hyde <query>         # HyDE transform
vant search <query> -r             # Rerank results
vant search --stats                # Index stats

vant rerank <query>                # Rerank for context
vant rerank compress <file>        # Compress a results file

vant embed list                    # Providers: hash, local, openai
vant embed set openai              # Set provider
vant embed info                    # Show provider info
vant embed generate "text"         # Generate an embedding
vant embed batch "one" "two"       # Batch embeddings

vant citations list               # List recorded sources
vant citations add <ref>          # Record a source (ref = commit hash)
vant citations verify <ref>       # Check whether a ref has been cited
vant citations search <query>     # Placeholder - not wired to the lib yet

vant geometry store <key> <val>    # Store in quasicrystal
vant geometry retrieve <key>       # Retrieve by key
vant geometry address <data>       # Store at random barcode
vant geometry locate <barcode>     # Retrieve by barcode

State entries are TTL-cached; set ttl/expiresAt through the memory lib API (memory.state(key, value, { ttl })) - there is no --ttl CLI flag.

Agents and runtime

Command	Description
`vant run`	Stub - prints runtime quickstart guidance (use `vant start` or `vant node`)
`vant node`	Persistent node (continuous run with brain loaded)
`vant agents`	Multi-agent management (list, spawn, kill, info, status, prune - real, persisted)
`vant islands`	Island component boot
`vant mcp`	MCP server for AI tools
`vant api`	API utilities (status, routes, call)
`vant org`	Operator grant utility (default `status`; `grant` persists unless `--session-only`; boot widens fresh processes)
`vant trust`	Reputation and trust scores
`vant resolution`	Thought resolution tracking
`vant succession`	Trust level management
`vant snapshot`	Verifiable stego-SVG brain snapshot
`vant brain-unlock`	Restore a brain from an SVG horcrux
`vant error`	Error code lookup and stats
`vant compute`	Multi-language compute runner

vant run                    # Stub: prints quickstart guidance and exits

vant node --mcp             # Node plus MCP server
vant node --mcp-port 4000   # Custom MCP port

vant agents list
vant agents spawn <name> [--role r] [--brain b]   # Real spawn; self-grants caps; persists
vant agents kill <id>                              # Real terminate; persists
vant agents info <id>

vant islands                # Show islands
vant islands boot           # Boot islands
vant islands load <name> [--as <agentId>]   # Load an island (optionally as an agent)
vant islands boundaries     # List RLS-gated islands + rules

vant mcp --stdio            # STDIO mode
vant mcp --server --port 3457

vant org grant                                  # Grant operator scopes+caps (persists by default; pass 123: bare `vant org` is status-only)
vant org grant --scopes read,write,spawn --capabilities canWrite,canSpawn
vant org grant --session-only                   # Throwaway session: don't persist
vant org status
vant org config --set-operator-scopes read,write,spawn   # Persist grant scopes
vant org config --set-operator-caps canRead,canWrite,canSpawn    # Persist grant caps
vant org demo                                   # Run the demo org flow

# (pass 88) Boot hydrates persisted orgchart.operatorCapabilities in every
# fresh process - `vant org grant` once, then CLI spawn/kill just work.

vant trust score <entity>
vant trust record <entity> <type> <delta>
vant trust leaderboard

vant resolution status
vant resolution resolve          # Mark resolved
vant resolution reject           # Mark rejected

vant succession                  # Show current trust level
vant succession get
vant succession set <level>

vant snapshot                    # Default output: <brain>/boot/<agent>-p_<pw>.svg
vant snapshot --agent nova       # Snapshot under a specific agent name
vant snapshot --brain nova       # Snapshot into a specific brain's boot dir
vant snapshot --password <pw>    # Explicit password
vant snapshot --output <path>    # Custom output path (inside the repo)
vant snapshot --no-verify        # Skip the round-trip verification
                                 # (REFUSED when overwriting an existing
                                 #  horcrux - see below)

# Backup safety: if the target already exists (i.e. it IS some brain's live
# boot horcrux), snapshot writes to a sibling tmp file, round-trip validates
# it, and only then replaces the original - same contract as
# `vant horcrux refresh`. A failed or corrupt encode never destroys the only
# backup. Brand-new targets write directly. The default output follows the
# current brain (models/public/<brain>/boot/<agent>-p_<pw>.svg), not a
# hardcoded brain name.

# Note: snapshot self-grants write on a fresh default sandbox (the CLI is
# trusted); a host that has explicitly locked the sandbox down must grant
# canWrite first. Sidecars (.manifest.json, .sha256) are gitignored. All
# paths resolve against the repo root regardless of invocation cwd.

vant error list
vant error code <code>
vant error explain <code>

vant node does not poll GitHub by default. Background sync is opt-in: --enable-polling, VANT_AGREE_AUTO_SYNC=true, or typing AGREE when prompted. It is intended for self-hosted GitLab/Gitea; on GitHub.com use vant sync.

MCP auth is optional and configured through vant config:

vant config set mcp.requireKey true
vant config set mcp.apiKey "your-secret-key"   # or: export VANT_MCP_API_KEY=...

Clients authenticate with X-API-Key: <key> or Authorization: Bearer <key>.

Storage

Command	Description
`vant storage`	Storage status and stats
`vant cache`	Cache management
`vant tmp`	Temp file management
`vant stream`	Stream operations
`vant wal`	Write-ahead journal status and recovery
`vant mirror`	Storage replication
`vant s3`	S3-compatible remote storage (S3, R2, MinIO, B2)
`vant backup`	Brain backup and restore
`vant horcrux`	Backup/restore brain to images
`vant transform`	Data gather and horcrux packaging
`vant compress`	Entropy encoder for brain files (.vpatch)
`vant stego`	Steganography encode/decode for images
`vant brain`	Brain mode control (dual/public/private/remote)
`vant format`	Format detection and conversion
`vant schema`	JSON/YAML schema validation
`vant universe`	Genesis snapshots + stored scenario manifests: derive/fork a world’s deterministic identity; record/diff/resume content-addressed manifests; resume `--materialize` restores recorded cell values escrow-gated (Wave U3) (`bin/universe.js`)
`vant scenario`	Governance playbook (Wave U3): scenario crew over one shared escrow pool, delegated task under quarantine+escrow+consensus gates, roster/pool status (`bin/scenario.js`)
`vant export`	Provenance/compliance bundle (Wave U5): `bundle --out <dir>` assembles a self-verifying bundle (registry manifest, citations, audit excerpt, encrypted horcrux, L-hashed running content manifest); `verify <dir>` recomputes the chain and FAILS CLOSED on tamper (`E_BUNDLE_TAMPERED`) (`bin/export.js`)

vant storage                # Show storage status
vant cache --clear          # Clear cache
vant universe snapshot my-world   # Derive (seed, cells, fingerprint) from (universe, name)
vant universe fork my-world child # Prefix-folded child world (fork = filename)
vant universe status        # Universe constant source + default-world fingerprint
vant universe record my-world --state-root <hash>  # Store a content-addressed manifest
vant universe record child.my-world --fork        # Record a folded fork manifest
vant universe diff <idA> <idB>      # Cell-hash delta (same-universe contract)
vant universe resume <id> --actor me  # Lock-gated, WAL-backed resume marker
vant scenario crew audit-world --agents 3 --budget 500   # Crew over one shared escrow pool
vant scenario task audit-world "Verify the pinned ledger" --cost 250  # Quarantine->escrow->consensus gates
vant scenario status audit-world  # Roster + live pool headroom
vant export bundle --out compliance-2026 --password <pw>  # Self-verifying bundle (Wave U5)
vant export verify compliance-2026        # Recompute the hash chain (fail-closed on tamper)
vant tmp list               # List temp files (workspace space)
vant tmp create "text"      # Create a temp file
vant tmp clean              # Clear the workspace temp space
vant tmp stats              # File count + task context

vant wal --status <basePath>  # Journal state (records, pending intents)
vant wal --drill <basePath>   # Reopen, replay, verify, report
vant wal --reset <basePath>   # Drop the journal (verify first)

vant mirror --status        # Replication config and stats
vant mirror --status --base <path> --mirror <path>...

vant s3 --status            # Config summary (no secrets printed)
vant s3 --test              # Connectivity probe
vant s3 --ls [prefix]       # List remote keys
vant s3 --push [--dry-run]  # Push local brain to remote
vant s3 --pull [--dry-run]  # Pull remote brain to local

vant backup create          # same backup-safety as snapshot/horcrux refresh:
                            # existing targets go through tmp->validate->replace,
                            # and the final file is re-verified after the swap
                            # (original restored if verification fails)
vant backup restore <file>   # validates the file first - wrong password /
                             # corrupt file fails before anything is restored
vant backup list
vant backup schedule         # not implemented - prints a cron recipe

vant horcrux inspect [path] [password]
vant horcrux restore [path] [password]
vant horcrux create [path] [password]
vant horcrux refresh [password]      # regenerate boot horcrux in place

vant transform gather
vant transform to-horcrux
vant transform inspect-horcrux <file>

vant compress <file_or_folder>         # Create .vpatch
vant compress <file> --output <dir>
vant compress <file> --window 16 --threshold 0.9
vant compress <file> --stats           # Entropy stats only
vant compress models/latent/x.vpatch --decompress

vant stego encode <input.txt> <image.png>   # Encode text in image
vant stego decode <stego.png>               # Decode from image

vant brain mode dual            # dual | public | private | remote

Network and messaging

Command	Description
`vant server`	HTTP/HTTPS server with security chain
`vant network`	Peer network operations
`vant nodes`	Peer discovery
`vant remote`	Remote add/remove/list
`vant msg`	Messaging system
`vant event`	Event handling
`vant telegram`	Telegram bot (bin/bot.js)

See also the Federation section below for cross-org verbs (genesis, agora, mesh, notices).

vant server --port 8080                  # Custom port
vant server --host 0.0.0.0               # Bind host
vant server --cert <path> --key <path>   # HTTPS

vant msg send <user> <msg>
vant msg --read

vant event --emit <name>
vant event --listen

vant telegram

Security

Command	Description
`vant sandbox`	Capability sandbox status
`vant vaf`	Input validation checks
`vant sudo`	Privilege elevation and metrics
`vant secret`	Secret management
`vant encrypt`	Encryption utilities
`vant rls`	Row-level security context
`vant security`	Security utilities
`vant legal`	Compliance tools
`vant escrow`	Escrow service for operations (reference)
`vant audit`	Generate an audit report
`vant audit-ledger`	Inspect rotated audit-ledger archives in models/audit-rotate/ (pass 118)

vant sandbox status
vant sandbox allow <capability>
vant sandbox deny <capability>

vant secret list              # List secret types
vant secret get <type>        # Get a secret (brain, github, ...)
vant secret set <type> <val>
vant secret clear <type>
vant secret clear --all

vant encrypt --encrypt file.txt
vant encrypt --decrypt file.enc
vant encrypt --keygen

vant rls init
vant rls workspace <name>

vant sudo --elevate
vant sudo --status
vant sudo --revoke
vant sudo metrics

vant audit --json
vant audit --out AUDIT.md      # --out FILE or --out=FILE; inside the repo

vant audit-ledger                          # list rotated ledger archives
vant audit-ledger --all                    # dump every archived entry (JSON)
vant audit-ledger audit-1770000000000.json # dump one archive
vant audit-ledger --all --action fatal --limit 20  # filter + newest N

Operations

Command	Description
`vant metrics`	Metrics registry dashboard
`vant cron`	Cron job scheduler
`vant clean`	Unified cleanup (logs, tmp, cache, prune)
`vant config`	Configuration get/set/list
`vant validate`	Schema, audit, and circuit validation
`vant auth`	Authentication management
`vant update`	Check for new releases
`vant bump`	Bump version and tag a release
`vant rate`	Rate limiter status and reset
`vant docs`	Build docs for release
`vant docs-build`	Docs build with version stamping
`vant summary`	Session summary
`vant changelog`	View recent changes
`vant system`	System diagnostics and layer status
`vant shell`	Shell operations
`vant boot`	Ghost boot from a stego image

vant metrics                    # Registry summary
vant metrics --prom             # Prometheus exposition format
vant metrics storage            # Per-store aggregation

vant cron list
vant cron add <spec> <cmd>
vant cron remove <id>
vant cron run <id>
vant cron status

vant clean --dry-run            # Preview without changes
vant clean logs                 # Clean logs only
vant clean tmp
vant clean cache
vant clean prune
vant clean all

vant config get <key>
vant config set <key> <value>
vant config list

vant validate --check           # Full validation

vant auth login <user>
vant auth logout

vant bump patch --yes           # Explicit type plus --yes is required
vant bump minor --yes
vant bump major --yes

vant rate                       # Rate limiter status
vant rate reset <clientId>

vant docs build                 # Build docs for release
vant docs serve                 # Serve locally (docsify)
vant docs-build

vant summary
vant changelog                  # Recent commits (default: 20)
vant changelog --since v0.7.0
vant changelog --format=short

vant system status
vant system healthy

Federation

Cross-org verbs: sovereign nodes meeting over the signed crew-bus wire. Concepts and playbooks: Federation and Federation Playbooks. The operator guide for a group’s steward install is the Steward Runbook.

Command	Description
`vant genesis`	Mesh join ceremony (create, join, status)
`vant agora`	Cross-node agora ops (nodes, status, vote, pull, push)
`vant mesh status`	Node + federated status view (–json, –peers)
`vant notices`	The board: post, list, pull, broadcast, bridge decisions
`vant node-registry`	Vetted node/principal registrations

# Pair join: their side hosts, yours joins with the out-of-band secret
vant genesis create --name acme-node --agent acme-1 --port 4890 --joiner beta-node --joiner-agent beta-1
vant genesis join --name beta-node --agent beta-1 --port 4891 --host acme-node --host-port 4890 --secret <pair-secret>
vant genesis status

# Cross-node agora: vote on a peer's topic; pull the ledger back
vant agora nodes
vant agora vote acme-node q3-platform-call thursday-1400utc
vant agora pull acme-node forum-q3-platform-call-abc123

# The board: post a plain notice, catch up after downtime
vant notices post "Q3 platform call set" --body "Thursday 1400 UTC, three orgs" --ttl-ms 604800000
vant notices list
vant notices pull --all
vant notices broadcast
vant notices bridge forum-q3-platform-call-abc123   # scoped topics refuse by design

# Observability
vant mesh status
vant mesh status --peers --json

Trust posture (unchanged across all of these): registered peers only, sender-bound replies, scope resolves where the model lives, merges re-derive status locally, and the wire never carries the ring secret.

Ecosystem

Experimental social, governance, and meta surfaces. Each is a real module with its own --help.

Command	Description
`vant teams`	Organization and team management (org, dept, team, assign)
`vant governance`	Governance decision making
`vant market`	Knowledge trading (list, bid, trade, search, stats) + paid skills (Wave U6.5/6.6 productized: `skill-list/buy/deliver/settle/status/sweep/gate` - delivery-confirmed settlement over real escrow, TTL evidence sweep for stale holds, shill-resistant pre-trade reputation; `skill-list --supply N\|Infinity` opts a skill into scarcity (default unlimited labor, enforced `E_SKILL_SOLD_OUT`); settlement identity: only the buyer of record settles; gated by `market.skillsEnabled`, env alias `VANT_MARKET_SKILLS_ENABLED`, sweep TTL `VANT_MARKET_SKILLS_TRADE_TTL_MS`) (reference, playbook)
`vant forum`	Forum and discussion (list, post, view, message) - tenancy-aware: anonymous sees the global commons only; votes ride consensus; `decisions <barcode>` inspects a thread’s deliberation->decision trail (link, ballots, escrow holds, voted outcome - Wave U4)

vant forum post "Adopt decision log" "We should persist outcomes"  # Publish (tenancy-stamped)
vant forum list                                                    # Publications visible to your tenancy
vant forum view PUB-1791683485237                                  # Read one

# Wave U4: a vote can belong to a thread - the decision trail reads back
vant forum decisions PUB-1791683485237      # link -> ballots -> escrow holds -> outcome
vant forum decisions PUB-1791683485237 --json   # machine-readable
vant forum links                            # every thread with a linked vote

vant teams                # Organization and team management
vant governance           # Governance decisions
vant skills list
vant skills search <q>
vant skills add <url>
vant skills remove <name>

vant theme show           # Render the live CLI/MCP surface (header + status icons)
vant theme status         # Theme config per brain on the stack
vant theme set accent '"#ff8800"'

vant connector list       # pinecone | qdrant | weaviate (the real factory surface)
vant connector status qdrant
vant connector connect qdrant

vant nodes list           # Registry view (adopts peer registrations)
vant nodes ping <id>      # Heartbeat liveness
vant node-registry status # total/alive/joining/dead + state-spine tree root

vant events tail [--follow]
vant qos status
vant mesh status --peers

vant canvas spiral [count]
vant canvas svg [name]
vant canvas markdown [name]
vant canvas share [name]

Internal

These commands support development and CI. Most users will not need them.

Command	Description
`vant test`	Test runner (`smoke`, `core`, `full` modes)
`vant spawn`	Agent spawning utility (routes bin/agent-spawner.js)
`vant telegram`	Telegram bot (bin/bot.js; needs TELEGRAM_BOT_TOKEN)
`vant hybrid`	Split sync (routes bin/hybrid-sync)
`vant branch`	Branch management (routes bin/branch-manager)
`vant test-all`	17-check self-test (health/search/islands/lib exports)

vant test          # Smoke tests (default)
vant test core     # Brain, storage, core modules
vant test full     # All tests (500+)

vant test-all      # 17 self-checks across health/search/islands/lib exports
                   # (routes bin/test-all.js; cwd-independent: runs from any directory)

vant spawn list    # List spawned agents
vant spawn --help  # Agent spawner usage
vant build-test    # Build verification (cwd-independent)
vant format-test   # format.js test suite (cwd-independent)

Some dev tools are invoked with node directly rather than through the vant dispatcher:

bash bin/sweep.sh        # Test health gate (or: bash bin/sweep.sh --quick)
node test/runner.js      # Raw test runner