@vivantel/virage-cli

@vivantel/virage-cli

CLI for the Virage RAG pipeline.

Installation

Install the CLI globally:

npm install -g @vivantel/virage-cli

Then set up a project:

cd my-project
virage init   # interactive wizard: selects embedder, vector store, agents; installs plugins
virage index  # index the codebase

virage init installs all required plugins (embedder, vector store, re-ranker, chunker, and agent plugins) to either ~/.virage/plugins (global) or $PROJECT_DIR/.virage/plugins (local). Installed versions are recorded in virage.config.json under pluginVersions.

Plugin management

Virage extensions — embedders, vector stores, re-rankers, and agent plugins — are managed by the CLI and stored in dedicated plugin directories:

Scope	Path
Local (per-project)	$PROJECT_DIR/.virage/plugins/
Global (all projects)	~/.virage/plugins/

Load priority: local > global. Install scope is chosen during virage init.

Use virage update to update installed plugins and resync agent configs.

Commands

Every top-level command has a single-key alias — use virage --help to see all of them.

Pipeline

Command	Alias	Description
virage index	i	Run the RAG indexing pipeline
virage check	c	Validate that the current embedder config matches the stored index
virage validate	val	Validate config without running the pipeline
virage query <text>	q	Semantic search over the indexed knowledge base

Setup & updates

Command	Alias	Description
virage init	—	Interactive wizard: configure embedder, vector store, re-ranker, hybrid search, and agent plugins; installs all selected plugins
virage update	up	Check for outdated plugins, update selected ones, and resync agent configs
virage install-hooks	hooks	Install git hooks for auto-indexing on pull/branch switch

Agent utilities

Command	Alias	Description
virage usage	use	Print per-prompt token usage for the current Claude Code session
virage read-skill-summary <name>	skill	Print the summary for a named Virage skill

Evaluation

All evaluation commands live under the virage eval (e) parent:

Command	Alias	Description
virage eval run	e run	One-shot retrieval quality check (precision@5/10, MRR, hit rate)
virage eval generate	e gen	Generate an eval dataset from existing indexed chunks
virage eval save --name <n>	—	Run evaluation and save results under a name for later comparison
virage eval list	—	List saved evaluation runs
virage eval compare --baseline --candidate	—	Bootstrap significance test between two saved runs
virage report	r	Show observability report from pipeline runs

Diagnostics

Command	Alias	Description
virage store stats	—	Show vector index quality metrics
virage store perf	—	Show query performance report
virage benchmark embedder	—	Benchmark embedder latency and throughput
virage chunks report	—	Show chunk cohesion report
virage viz embeddings	—	Generate a 2D visualization of the embedding space
virage dashboard	d	Start a local RAG monitoring dashboard

Telemetry

Command	Description
virage telemetry status	Show telemetry status, buffer size, and endpoint health
virage telemetry on	Enable telemetry collection
virage telemetry off	Disable telemetry collection and clear local buffer
virage telemetry init	Interactive telemetry configuration wizard
virage telemetry preview	Preview the telemetry payload (no transmission)
virage telemetry flush	Flush buffered telemetry to the configured endpoint

Configuration

All configuration lives in virage.config.json. The $schema field enables IDE autocomplete and inline validation. ${ENV_VAR} patterns are expanded from the environment at runtime.

{
  "$schema": "https://unpkg.com/@vivantel/virage-core/schemas/virage.config.schema.json",
  "chunking": {
    "exclude": [
      "**/vendor/**", "**/*.min.js", "**/*.min.css",
      "**/*.lock", "**/dist/**", "**/target/**"
    ],
    "chunkers": [
      { "patterns": ["**/*.md"], "strategy": "markdownHeaders" },
      { "patterns": ["src/**/*.ts"], "strategy": "codeChunkAst" }
    ]
  },
  "agents": ["claude-code"],
  "embedder": {
    "package": "@vivantel/virage-embedder-transformers",
    "config": { "model": "Xenova/all-MiniLM-L6-v2", "dimensions": 384 }
  },
  "vectorStore": {
    "package": "@vivantel/virage-store-lancedb",
    "config": { "uri": ".virage/lancedb" }
  },
  "search": {
    "hybrid": true,
    "hybridAlpha": 0.6,
    "reranker": {
      "package": "@vivantel/virage-reranker-cross-encoder",
      "config": { "model": "Xenova/ms-marco-MiniLM-L-6-v2", "topK": 5 }
    }
  },
  "pluginVersions": {
    "@vivantel/virage-embedder-transformers": "0.2.36",
    "@vivantel/virage-store-lancedb": "0.2.36",
    "@vivantel/virage-reranker-cross-encoder": "0.1.8",
    "@vivantel/virage-code-chunk-chunker": "0.1.19",
    "@vivantel/virage-agent-claude": "0.2.24"
  }
}

chunking.exclude accepts glob patterns excluded from all chunkers globally. virage init seeds this with ecosystem-specific defaults. Old configs with chunkers at the root are auto-normalized on load.

Embedders

Package	Requires API key	Notes
@vivantel/virage-embedder-openai	Yes	OpenAI, Azure, GitHub Models, Ollama, any OpenAI-compatible endpoint
@vivantel/virage-embedder-fastembed	No	Fast local ONNX inference; good default for offline use
@vivantel/virage-embedder-transformers	No	HuggingFace Transformers.js; wider model selection

Vector stores

Package	Infrastructure	Best for
@vivantel/virage-store-lancedb	None (file-based)	Local dev, CI, small projects
@vivantel/virage-store-postgres	PostgreSQL + pgvector	Production, complex SQL queries
@vivantel/virage-store-qdrant	Qdrant (Docker or cloud)	High-scale, distributed deployments
@vivantel/virage-store-chromadb	ChromaDB (Docker or hosted)	Simple hosted deployments

Re-rankers

Optional post-retrieval re-rankers improve result precision by re-scoring the top-K candidates.

Package	Requires API key	Notes
@vivantel/virage-reranker-cross-encoder	No	Local ONNX cross-encoder; no API key required
@vivantel/virage-reranker-llm	Yes (Anthropic)	LLM-based re-ranker using claude-haiku-4-5

Agent plugins

Agent plugins configure AI coding assistants to use Virage for semantic search and context retrieval. Selected during virage init, they are installed to the plugin dir and their configure() function is run to write vendor-native config files (hooks, MCP registration, slash commands).

Package	Agent	Config written
@vivantel/virage-agent-claude	Claude Code	.claude/skills/virage-agent/ + MCP server registration
@vivantel/virage-agent-copilot	GitHub Copilot	.github/copilot/ (hooks.json, instructions/)
@vivantel/virage-agent-codex	OpenAI Codex	.codex/ (hooks.json)
@vivantel/virage-agent-antigravity	Google Antigravity	.antigravity/ (hooks.json)

Options

All commands accept -v / -vv / -vvv (up to -vvvvv) to increase log verbosity.

Most pipeline commands accept -c, --config <path> to specify a config file (default: ./virage.config.json).

virage dashboard additionally accepts --port <n> (default: 3000) and --verbose (log all HTTP requests).

Startup banner

Virage prints a one-line banner (Virage vX.Y.Z N chunkers · embedder · store) on startup. To suppress it:

• CLI flag: virage --no-banner <command>
• Environment variable: VIRAGE_NO_BANNER=1 virage <command>
• Config file: set "options": { "noBanner": true } in virage.config.json

The banner is automatically suppressed when stdout is not a TTY (piped output, CI, etc.).