When to use

• Index codebases or documents for semantic search
• Query vector stores for relevant code/document chunks
• Manage vector stores (create, delete, list)
• Set up local RAG with Ollama embeddings

vector-rag-tool Skill

Purpose

CLI for local RAG (Retrieval-Augmented Generation) with Ollama embeddings and FAISS vector search. Index codebases and documents into vector stores for semantic search.

When to Use

Use this skill when:

• Indexing source code or documentation for semantic search
• Querying indexed content by meaning (not just keywords)
• Managing vector stores (create, list, delete, info)
• Configuring S3 Vectors backend for cloud storage

Do NOT use for:

• Simple text search (use grep instead)
• Tasks unrelated to vector search or RAG

Prerequisites

# Ollama with embedding model
brew install ollama
ollama pull embeddinggemma

Quick Start

# Index Python files
vector-rag-tool index "**/*.py" --store my-project --no-dry-run

# Query for relevant code
vector-rag-tool query "how does authentication work" --store my-project

# List stores
vector-rag-tool store list

Commands

index - Index files into vector store

# Preview (dry-run default)
vector-rag-tool index "*.py" --store my-store

# Actually index files
vector-rag-tool index "*.md" "*.py" --store my-store --no-dry-run

# Index to S3 Vectors
vector-rag-tool index "src/**/*.py" --store my-store \
    --bucket my-vectors-bucket --profile dev --no-dry-run

# Force reindex all
vector-rag-tool index "docs/**/*.md" --store my-store --force --no-dry-run

# Custom chunk size
vector-rag-tool index "**/*.py" --store my-store --chunk-size 500 --no-dry-run

Options:

Option	Description
--store/-s	Store name (required)
--bucket/-b	S3 bucket for remote storage
--region/-r	AWS region (default: eu-central-1)
--profile/-p	AWS profile name
--dry-run/-n	Preview mode (default: enabled)
--no-dry-run	Actually perform indexing
--force/-f	Force reindexing all files
--chunk-size/-c	Target chunk size (default: 1500)
--chunk-overlap/-o	Overlap between chunks (default: 200)
-v/-vv/-vvv	Verbosity (INFO/DEBUG/TRACE)

query - Query vector store

# Basic query
vector-rag-tool query "machine learning" --store my-store

# More results
vector-rag-tool query "deep learning" --store my-store --top-k 10

# Query S3 backend
vector-rag-tool query "neural networks" --store my-store \
    --bucket my-vector-store --profile dev

# JSON output
vector-rag-tool query "attention mechanism" --store my-store --json

# From stdin
echo "query text" | vector-rag-tool query --store my-store --stdin

# Full chunks for RAG grounding
vector-rag-tool query "authentication" --store my-store --full --json

Options:

Option	Description
--store/-s	Store name (required)
--top-k/-k	Number of results (default: 5)
--json	JSON output
--stdin	Read query from stdin
--snippet-length/-l	Max snippet length (default: 300)
--full/-F	Return full chunk content

Output format:

{
  "query": "authentication",
  "store": "my-store",
  "total_results": 5,
  "results": [
    {
      "score": 0.85,
      "file_path": "src/auth.py",
      "line_start": 42,
      "line_end": 78,
      "content": "..."
    }
  ]
}

store - Manage vector stores

# List stores
vector-rag-tool store list
vector-rag-tool store list --format json

# Create store
vector-rag-tool store create my-store
vector-rag-tool store create my-store --dimension 1536

# Store info
vector-rag-tool store info my-store
vector-rag-tool store info my-store --format json

# Delete store
vector-rag-tool store delete my-store
vector-rag-tool store delete my-store --force

completion - Shell completion

# Bash
eval "$(vector-rag-tool completion bash)"

# Zsh
eval "$(vector-rag-tool completion zsh)"

# Fish
vector-rag-tool completion fish > ~/.config/fish/completions/vector-rag-tool.fish

Chunking Guidelines

Use Case	Chunk Size	Rationale
Code search	1000-1500	Full functions/classes
Documentation	500-1000	Paragraphs and sections
Fine-grained	300-500	More specific matches

Verbosity Levels

Flag	Level	Output
(none)	WARNING	Errors and warnings only
-v	INFO	High-level operations
-vv	DEBUG	Detailed info
-vvv	TRACE	Library internals

Troubleshooting

# Verify installation
vector-rag-tool --version

# Verify Ollama
ollama list  # Should show embeddinggemma

# List stores
vector-rag-tool store list

# Check store info
vector-rag-tool store info my-store

# Debug mode
vector-rag-tool query "test" --store my-store -vv

Exit Codes

• 0: Success
• 1: Client error (invalid arguments)
• 2: Server error (backend error)